> This page is for version 3.0 (Latest) (default).
> For other versions, use one of these documentation indexes:
> - 3.0 (Latest) (default): https://docs.nvidia.com/holoscan/sensor-bridge/3-0/llms.txt
> - 2.7: https://docs.nvidia.com/holoscan/sensor-bridge/2-7/llms.txt
> - Archives: https://docs.nvidia.com/holoscan/sensor-bridge/archives/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/holoscan/sensor-bridge/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/holoscan/sensor-bridge/_mcp/server.

# hololink::module::HololinkInterfaceV1

> Access features on an HSB device.

Access features on an HSB device.

This is the application's handle to the device itself: it opens and closes the control plane, drives the device into a known state, reads and writes device registers, and hands out the other services that work on this device – data channels, I2C buses, sequencers and VSYNC sources.

Fetch it with the [EnumerationMetadata](enumerationmetadata) describing the device, then bring the device up before configuring a sensor on it:

```cpp showLineNumbers={false}
#include <hololink/module/hololink.hpp>
```

## Example

```cpp showLineNumbers={false}
auto& adapter = hololink::module::Adapter::get_adapter();
auto metadata = adapter.wait_for_channel(hololink_ip, discovery_timeout);
auto hololink = hololink::module::HololinkInterfaceV1::get_service(metadata);
// No device I/O works until the control plane is open.
hololink->start();
// The framework leaves device state alone unless the application asks;
// reset() drives the board into a known state.
hololink->reset();
// ... configure sensors, run the pipeline ...
// Close connections to the device.
hololink->stop();
```

**Inherits from:** `hololink::module::ConfigurableService< HololinkInterfaceV1 >` (public), `std::enable_shared_from_this< HololinkInterfaceV1 >` (public)

---

## Methods

### enumeration_metadata \[#enumerationmetadata]

```cpp showLineNumbers={false}
virtual const EnumerationMetadata & hololink::module::HololinkInterfaceV1::enumeration_metadata() const
```

The enumeration metadata this device was configured with.

Services sharing this device read the configuration metadata from this snapshot rather than keeping a copy of their own, so they are all built from the same values.

### start \[#start]

```cpp showLineNumbers={false}
virtual hololink_module_status_t hololink::module::HololinkInterfaceV1::start()
```

Open the control plane to the device.

Register access, I2C traffic and anything else that reaches the device works only while the control plane is open, so an application calls this before configuring the device. Calling it again while it is open does nothing.

**Returns:** HOLOLINK_MODULE_OK or an error status.

### stop \[#stop]

```cpp showLineNumbers={false}
virtual hololink_module_status_t hololink::module::HololinkInterfaceV1::stop()
```

Close the control plane to the device.

Applications call this when they are done with the device; it does nothing if the control plane is already closed.

**Returns:** HOLOLINK_MODULE_OK or an error status.

### reset \[#reset]

```cpp showLineNumbers={false}
virtual hololink_module_status_t hololink::module::HololinkInterfaceV1::reset()
```

Drive the device into a known state.

Resets the device, waits for it to come back and announce itself, then applies the configuration the control plane needs. Every callback registered through on_reset() fires. Applications reset a device before configuring the sensors on it: the framework changes no device state on its own.

**Returns:** HOLOLINK_MODULE_OK or an error status.

### device_lost \[#devicelost]

```cpp showLineNumbers={false}
virtual hololink_module_status_t hololink::module::HololinkInterfaceV1::device_lost()
```

Invalidate the services cached for this device, following loss of contact with it.

Services built for a device accumulate device state, which goes stale when the device is lost. Once an application discovers the loss it calls this, and the framework drops its references to those service objects. When the device comes back and is enumerated again, calls to [`get_service`](configurableservice#getservice) build new instances, in sync with the recovered device. The application drops its own references to the older objects; calls on those stale instances fail in ways that depend on the service.

**Returns:** HOLOLINK_MODULE_OK or an error status.

### ptp_synchronize \[#ptpsynchronize]

```cpp showLineNumbers={false}
virtual bool hololink::module::HololinkInterfaceV1::ptp_synchronize()
```

Wait for the device's clock to synchronize with the PTP grandmaster.

Blocks until the device's clock is disciplined, so that the timestamps it reports with each frame share the host's PTP domain. Applications that rely on those timestamps call this after start() or reset().

**Returns:** True once the clock is synchronized; false if it did not synchronize within a default timeout.

### on_reset \[#onreset]

```cpp showLineNumbers={false}
virtual std::shared_ptr<ResetRegistration> hololink::module::HololinkInterfaceV1::on_reset(
    std::function<void()> callback
)
```

Register a callback fired each time this device completes a reset.

The callback runs once per reset(), after the device has rebooted and its HSB configuration has been re-applied. Sensor drivers register here to drop the hardware state they cached, so the next configuration pass writes it to the device again. Any number of callbacks may be registered.

**Returns:** Handle keeping the callback registered; destroying it unregisters the callback.

**Parameters**

**`callback`** `std::function<void()>`

Invoked once per reset of this device.

---

### write_uint32 \[#writeuint32]

```cpp showLineNumbers={false}
virtual hololink_module_status_t hololink::module::HololinkInterfaceV1::write_uint32(
    const std::vector<uint32_t> &addresses,
    const std::vector<uint32_t> &values
)
```

Write to locations within the HSB IP local bus.

**Returns:** HOLOLINK_MODULE_OK, or HOLOLINK_MODULE_INVALID_PARAMETER when the two lists differ in length.

**Parameters**

**`addresses`** `const std::vector<uint32_t> &`

Device addresses to write.

---

**`values`** `const std::vector<uint32_t> &`

The value written to each address.

---

### read_uint32 \[#readuint32]

```cpp showLineNumbers={false}
virtual hololink_module_status_t hololink::module::HololinkInterfaceV1::read_uint32(
    const std::vector<uint32_t> &addresses,
    std::vector<uint32_t> &out_values
)
```

Read locations within the HSB IP local bus.

**Returns:** HOLOLINK_MODULE_OK or an error status.

**Parameters**

**`addresses`** `const std::vector<uint32_t> &`

Device addresses to read.

---

**`out_values`** `std::vector<uint32_t> &`

Receives one value per address, in the order the addresses were given.

---

### and_uint32 \[#anduint32]

```cpp showLineNumbers={false}
virtual hololink_module_status_t hololink::module::HololinkInterfaceV1::and_uint32(
    uint32_t address,
    uint32_t mask
)
```

Clear bits in an HSB IP local bus location.

Reads the register, ANDs the value with `mask`, and writes it back.

**Returns:** HOLOLINK_MODULE_OK or an error status.

**Parameters**

**`address`** `uint32_t`

Device address to update.

---

**`mask`** `uint32_t`

Value ANDed with the register's contents.

---

### or_uint32 \[#oruint32]

```cpp showLineNumbers={false}
virtual hololink_module_status_t hololink::module::HololinkInterfaceV1::or_uint32(
    uint32_t address,
    uint32_t mask
)
```

Set bits in an HSB IP local bus location.

Reads the register, ORs the value with `mask`, and writes it back.

**Returns:** HOLOLINK_MODULE_OK or an error status.

**Parameters**

**`address`** `uint32_t`

Device address to update.

---

**`mask`** `uint32_t`

Value ORed with the register's contents.

---

### get_i2c \[#geti2c]

```cpp showLineNumbers={false}
template <typename T = I2cInterfaceV1>
std::shared_ptr<T> hololink::module::HololinkInterfaceV1::get_i2c(
    uint32_t bus,
    uint32_t address,
    bool allow_null = false
)
```

Fetch a I2C driver object.

The bus reaches every peripheral on it; each transaction names the peripheral it addresses.

**Returns:** The I2C interface for that bus.

**Template parameters**

**`T`** `typename`

The interface version to fetch.

---

**Parameters**

**`bus`** `uint32_t`

Which bus number within the device.

---

**`address`** `uint32_t`

Names the instance to fetch; a separate handle comes back per value.

---

**`allow_null`** `bool` — default: false

Return an empty pointer, rather than throwing, when this device publishes no such bus.

---

### software_sequencer \[#softwaresequencer]

```cpp showLineNumbers={false}
template <typename T = SequencerInterfaceV1>
std::shared_ptr<T> hololink::module::HololinkInterfaceV1::software_sequencer(
    bool allow_null = false
)
```

Sequencer for use with immediately triggered sequences.

Sequencers are implemented within the HSB IP to trigger sets of HSB IP local bus transactions (e.g. to execute an I2C transaction) on a specific flag (e.g. a GPIO or frame-done event). Use this sequencer when you want a sequence to run immediately.

**Returns:** The sequencer.

**Template parameters**

**`T`** `typename`

The interface version to fetch.

---

**Parameters**

**`allow_null`** `bool` — default: false

Return an empty pointer, rather than throwing, when this device publishes no such sequencer.

---

### gpio0_sequencer \[#gpio0sequencer]

```cpp showLineNumbers={false}
template <typename T = SequencerInterfaceV1>
std::shared_ptr<T> hololink::module::HololinkInterfaceV1::gpio0_sequencer(
    bool allow_null = false
)
```

Sequencer to trigger a sequence when GPIO0 is active.

**Returns:** The sequencer.

**Template parameters**

**`T`** `typename`

The interface version to fetch.

---

**Parameters**

**`allow_null`** `bool` — default: false

Return an empty pointer, rather than throwing, when this device publishes no such sequencer.

---

### gpio1_sequencer \[#gpio1sequencer]

```cpp showLineNumbers={false}
template <typename T = SequencerInterfaceV1>
std::shared_ptr<T> hololink::module::HololinkInterfaceV1::gpio1_sequencer(
    bool allow_null = false
)
```

Sequencer to trigger a sequence when GPIO1 is active.

**Returns:** The sequencer.

**Template parameters**

**`T`** `typename`

The interface version to fetch.

---

**Parameters**

**`allow_null`** `bool` — default: false

Return an empty pointer, rather than throwing, when this device publishes no such sequencer.

---

### sif0_frame_start_sequencer \[#sif0framestartsequencer]

```cpp showLineNumbers={false}
template <typename T = SequencerInterfaceV1>
std::shared_ptr<T> hololink::module::HololinkInterfaceV1::sif0_frame_start_sequencer(
    bool allow_null = false
)
```

Sequencer to trigger a sequence when SIF0 (sensor interface 0) receives the first data from a sensor following a frame end condition.

**Returns:** The sequencer.

**Template parameters**

**`T`** `typename`

The interface version to fetch.

---

**Parameters**

**`allow_null`** `bool` — default: false

Return an empty pointer, rather than throwing, when this device publishes no such sequencer.

---

### sif1_frame_start_sequencer \[#sif1framestartsequencer]

```cpp showLineNumbers={false}
template <typename T = SequencerInterfaceV1>
std::shared_ptr<T> hololink::module::HololinkInterfaceV1::sif1_frame_start_sequencer(
    bool allow_null = false
)
```

Sequencer to trigger a sequence when SIF1 (sensor interface 1) receives the first data from a sensor following a frame end condition.

**Returns:** The sequencer.

**Template parameters**

**`T`** `typename`

The interface version to fetch.

---

**Parameters**

**`allow_null`** `bool` — default: false

Return an empty pointer, rather than throwing, when this device publishes no such sequencer.

---

### ptp_pps_output \[#ptpppsoutput]

```cpp showLineNumbers={false}
template <typename T = PtpPpsOutputInterfaceV1>
std::shared_ptr<T> hololink::module::HololinkInterfaceV1::ptp_pps_output(
    bool allow_null = false
)
```

Fetch a PTP-based PPS output controller, for use with sensors that can be triggered externally (e.g.

cameras with VSYNC inputs).

One PTP PPS output serves the whole device, driven by the PPS the device's PTP-disciplined clock produces. Use the object returned here to configure the PPS rate; this same object is usually passed in to a device driver to ask it to use that as the sample trigger input.

**Returns:** the PPS controller based on PTP

**Template parameters**

**`T`** `typename`

The interface version to fetch.

---

**Parameters**

**`allow_null`** `bool` — default: false

Return an empty pointer, rather than throwing, when this device publishes no VSYNC source.

---

### null_vsync \[#nullvsync]

```cpp showLineNumbers={false}
template <typename T = VsyncInterfaceV1>
std::shared_ptr<T> hololink::module::HololinkInterfaceV1::null_vsync(
    bool allow_null = false
)
```

When a sensor takes a PPS sync input, use this instance to configure the device for free-running (unsynchronized) operation.

**Returns:** The VSYNC source.

**Template parameters**

**`T`** `typename`

The interface version to fetch.

---

**Parameters**

**`allow_null`** `bool` — default: false

Return an empty pointer, rather than throwing, when this device publishes no such source.

---

### configure \[#configure]

```cpp showLineNumbers={false}
virtual void hololink::module::ConfigurableService<HololinkInterfaceV1>::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.

### module \[#module]

```cpp showLineNumbers={false}
std::shared_ptr<Module> hololink::module::ServiceBase::module() const
```

The [Module](module) that this service was published from.

The service holds no strong reference to its [Module](module), so this does not extend the [Module](module)'s lifetime.

**Returns:** The owning [Module](module), or an empty pointer if the service has not been published or its [Module](module) no longer exists.

---

## Static methods

### get_service \[#getservice]

#### Fetch a service

```cpp showLineNumbers={false}
static std::shared_ptr<HololinkInterfaceV1> hololink::module::ConfigurableService<HololinkInterfaceV1>::get_service(
    const EnumerationMetadata &metadata,
    bool allow_null = false
)
```

Fetch a service, configured by [EnumerationMetadata](enumerationmetadata).

[Module](module) usually caches service objects; so when a specific service instance isn't found, it will be constructed with the current values in [EnumerationMetadata](enumerationmetadata). Later calls to get_service are likely to return that cached instance, ignoring changes to any enumeration metadata that aren't specifically related to service addressing.

**Returns:** A shared pointer to the requested service (\<Derived>).

**Throws:** `std::runtime_error` when allow_null==false and the service lookup (or construction) fails.

**Parameters**

**`metadata`** `const EnumerationMetadata &`

Addressing and configuration for the service.

---

**`allow_null`** `bool` — default: false

Use `true` to return nullptr when the service cannot be resolved; the default `false` value raises a std::runtime_error.

---

#### Overload 2

inline

```cpp showLineNumbers={false}
static std::shared_ptr<HololinkInterfaceV1> hololink::module::Service<HololinkInterfaceV1>::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](module).

Note that [Module](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`** `bool` — default: 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 \[#foreachtypeid]

```cpp showLineNumbers={false}
static bool hololink::module::Service<HololinkInterfaceV1>::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.

---

## Inner classes

### ResetRegistration

```cpp showLineNumbers={false}
class hololink::module::HololinkInterfaceV1::ResetRegistration
```

Handle to a callback registered with on_reset().

The callback fires while the handle is held, and is unregistered when the handle is destroyed. Hold it for as long as the callback should fire.