### Workspace Setup

If you are not using this node in an existing project, create a new
folder `ros2_ws`, then create the `src` folder in `ros2_ws`. Go to src
folder (either in ros2\_ws or in your project), and clone the adi\_iio
repository (make sure to clone the correct branch for your ROS2
version):


``` {.sourceCode .bash}
export COLCON_WS=~/ros2_ws
mkdir -p $COLCON_WS/src
cd $COLCON_WS/src
git clone --branch humble https://github.com/analogdevicesinc/iio_ros2.git

:::

### Resolving Dependencies

Before building the workspace, you need to resolve the package
dependencies. From the root of your workspace, run the following
command:


``` {.sourceCode .bash}
cd $COLCON_WS
rosdep update
rosdep install -i --from-path src --rosdistro ${ROS_DISTRO} -y --ignore-src

:::

::: {#(Optional) Build libiio from sources}
::: {.note}
::: {.admonition-title}
Note
:::

**Optional: Build Libiio from Source**

The [adi\_iio]{.title-ref} package supports an alternative method of
installing the libiio dependency by building it from source. This is
useful if you prefer to use a custom version of libiio instead of
relying on the system-provided `libiio-dev` package via rosdep.

To build libiio from source, run the provided installation script which
offers two options:

-   Set the desired libiio version (default is `libiio-v0`).
-   Specify the staging directory for the source build (default is
    `$HOME/src`).

For example:


``` {.sourceCode .bash}
# Optional exports
export LIBIIO_VERSION=libiio-v0
export STAGING_DIR=$HOME/src

cd ${COLCON_WS}/src/iio_ros2
./ci/install_dependencies.sh

:::
:::

### Building the Workspace

You can now build your package using the command:


``` {.sourceCode .bash}
colcon build --event-handlers console_cohesion+

Now you can run the `adi_iio` package.

`adi_iio` - Node-Specific Concepts {#node_specific_concepts}
==================================

This section provides a concise overview of the node-specific concepts
for the ROS2 package. It details the conventions for attribute paths,
topic naming, service responses, and buffer operations used when
interfacing with IIO devices.

IIO Path {#iio_path}
--------

Services use the `iio_path` parameter to uniquely identify Industrial
I/O (IIO) devices, channels, and attributes following the IIO context
hierarchy. The `/` character is used to separate different levels of the
hierarchy.

### Context Path

-   **Description:** an empty string is used to represent an IIO
    context.
-   **Format:** `""` (empty string.)

### Context Attribute Path (`attr_path`)

-   **Description:** this path represents an attribute of a context.
-   **Format:** `<context-attribute>`
-   **Example:** `uri`, `hw_vendor`, `hw_serial`, etc.

### Device Path (`device_path`)

-   **Description:** this path represents a device of a context.
-   **Format:** `<device-name>`
-   **Example:** `ad9361-phy`, `ad5592r`, etc.

### Device Attribute Path (`attr_path`)

-   **Description:** this path represents an attribute of a device.
-   **Format:** `<device-name>/<device-attribute>`
-   **Example:** `xadc/sampling_frequency`, etc.

### Channel Path (`channel_path`)

-   **Description:** this path represents a channel of a device.
-   **Format:** `<device-name>/<channel-name>`
-   **Example:** `ad5592r/input_voltage0`, `ad5592r/output_voltage0`,
    `ad9361-phy/voltage0`, etc.
-   **Note:** the channel name has an extended format which uses a
    prefix: `input_` or `output_` to indicate the direction of data flow
    for channels that share the same name. For example,
    `ad5592r/input_voltage0` and `ad5592r/output_voltage0` are both
    valid paths that refer to two different channels of the same device.
    When the prefix is not used (e.g: `ad5592r/voltage0`) but the device
    has both input and output channels, the input channel has priority.

### Channel Attribute Path (`attr_path`)

-   **Description:** this path represents an attribute of a channel.
-   **Format:** `<device-name>/<channel-name>/<channel-attribute>`
-   **Example:** `ad5592r/input_voltage0/scale`,
    `ad5592r/output_voltage0/scale`,
    `/cf-ad9361-lpc/voltage0/sampling_frequency`, etc.

Topic Name Resolution {#topic_name_resolution}
---------------------

The `EnableTopic` services can take an optional `topic_name` parameter.
When enabling the topic, the provided `topic_name` will be used. The
default value for this parameter is `""`. When this default is used, the
specific device/channel attribute name is prefixed with the node name.
For topics that deal with attributes, two topics will be created for
read and write operations. These topics are suffixed with `/read` and
`/write`. To adhere to ROS2 topic naming standards, the hyphen `-` is
replaced by an underscore `_`.

**Example:**

-   An adi-iio node named `radio` that enables the topic
    `/cf-ad9361-lpc/voltage0/sampling_frequency` will publish to
    `/radio/cf_ad9361_lpc/voltage0/sampling_frequency/read` and
    subscribe to
    `/radio/cf_ad9361_lpc/voltage0/sampling_frequency/write` for
    updates.

Service Responses {#service_responses}
-----------------

All service responses contain at least two fields: a boolean indicating
success and a string message.


``` {.sourceCode .}
AttrReadString.srv:

string attr_path
---
bool success
string message

`adi_iio` - Node Description {#Node Description}
============================

Parameters
----------

The node accepts the following parameters:

-   `uri`: The URI of the LibIIO context where the device is connected
    to (e.g.: `ip:192.168.2.1`)

Services
--------

The node provides the following services:

### AttrDisableTopic {#AttrDisableTopic}

**Description:** Disables the topic associated with a specific
attribute.

**Request:**

-   `attr_path` (string): The path to the attribute to be disabled.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.

### AttrEnableTopic {#AttrEnableTopic}

**Description:** Enables a topic for a specific attribute.

**Request:**

-   `attr_path` (string): The path to the attribute for which a topic
    will be enabled.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.

### AttrReadString {#AttrReadString}

**Description:** Reads an IIO attribute as a string.

**Request:**

-   `attr_path` (string): The path to the attribute to be read.

**Response:**

-   `value` (string): The value of the attribute.
-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.

### AttrWriteString {#AttrWriteString}

**Description:** Writes an IIO attribute as a string

**Request:**

-   `attr_path` (string): The path to the attribute to be written.
-   `value` (string): The value to be written to the attribute.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.

### BufferCreate {#BufferCreate}

**Description:** Creates a buffer.

**Request:**

-   `device_path` (string): The path to the device.
-   `channels` (string\[\]): The channels to be read from the buffer.
-   `samples_count` (int32): The number of samples for the buffer.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.

### BufferDestroy {#BufferDestroy}

**Description:** Destroys a buffer.

**Request:**

-   `device_path` (string): The path to the device.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.

### BufferDisableTopic {#BufferDisableTopic}

**Description:** Disables a topic for a buffer.

**Request:** \* `device_path` (string): The path to the device.

**Response:** \* `success` (bool): Indicates whether the operation was
successful. \* `message` (string): A message providing additional
information.

### BufferEnableTopic {#BufferEnableTopic}

**Description:** Enables a topic for a buffer.

**Request:**

-   `device_path` (string): The path to the device.
-   `topic_name` (string): The name of the topic to be enabled.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.

### BufferRead {#BufferRead}

**Description:** Reads data from a buffer.

**Request:**

-   `device_path` (string): The path to the device.
-   `channels` (string\[\]): The channels to be read from the buffer.
-   `samples_count` (int32): The number of samples to read.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.
-   `buffer` (Int32MultiArray): The data read from the buffer.

### BufferRefill {#BufferRefill}

**Description:** Refills a buffer.

**Request:**

-   `device_path` (string): The path to the device.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.
-   `buffer` (Int32MultiArray): The data read from the buffer after
    refilling.

### BufferWrite {#BufferWrite}

**Description:** Writes data to a buffer.

**Request:**

-   `device_path` (string): The path to the device.
-   `channels` (string\[\]): The channels where data will be written.
-   `buffer` (Int32MultiArray): The data to be written to the buffer.
-   `cyclic` (bool): Indicates whether the buffer should be cyclic.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.

### ScanContext {#ScanContext}

**Description:** Scans the current IIO context and returns lists of
devices, channels, and attributes formatted as IIO paths which can be
used as request parameters for the other services.

**Request:**

-   None. The operation uses the `uri` provided during node
    initialization to scan for devices.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.
-   `devices` (string\[\]): A list of IIO paths to the discovered
    devices.
-   `channels` (string\[\]): A list of IIO paths to the discovered
    channels.
-   `context_attrs` (string\[\]): A list of IIO paths to the discovered
    context attributes.
-   `device_attrs` (string\[\]): A list of IIO paths to the discovered
    device attributes.
-   `channel_attrs` (string\[\]): A list of IIO paths to the discovered
    channel attributes.

### ListDevices {#ListDevices}

**Description:** Lists the IIO device paths found in the current
context.

**Request:**

-   None. The operation uses the `uri` provided during node
    initialization to scan for devices.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.
-   `data` (string\[\]): A list containing the IIO device paths.

### ListChannels {#ListChannels}

**Description:** Lists the IIO channel paths found in the targeted
device.

**Request:**

-   `iio_path` (string): The IIO path to the device to be scanned.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.
-   `data` (string\[\]): A list containing the IIO channel paths.

### ListAttributes {#ListAttributes}

**Description:** Lists the IIO attribute paths found in the target path.
This can be either a context, device, or channel path.

**Request:**

-   `iio_path` (string): The IIO path to a context,device or channel to
    be scanned.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.
-   `data` (string\[\]): A list containing the IIO attribute paths.

Launch
------

To launch the node, you can use the provided launch file
`adi_iio_bringup.launch.py`. This launch file uses the the `uri`
parameter defined in the `config/adi_iio.yaml` file.

The project also contains a small python script to visualize the
waveform using matplotlib plots. The `topic` parameter is used to
subscribe to the topic where the waveform is published and plot the
waveforms.


``` {.sourceCode .bash}
ros2 launch adi_iio adi_iio_bringup.launch.py
python3 visualize_iio_waveform.py --topic /m2k_adc

2.  **Activate the Virtual Environment**

    
``` {.sourceCode .bash}
    source .venv/bin/activate
    

4.  **Source the Virtual Environment**

    
``` {.sourceCode .bash}
    source .venv/bin/activate