libbladeRF: Streaming

| libbladeRF 2.2.1-git Nuand bladeRF library

Modules | Typedefs | Macros | Functions
Streaming

## Description

This section defines the streaming APIs.

## Modules
| Formats
| This section defines the available sample formats and metadata flags.
| Synchronous API
| This group of functions presents synchronous, blocking calls (with optional timeouts) for transmitting and receiving samples.
| Asynchronous API
| This interface gives the API user full control over the stream and buffer management, at the cost of added complexity.

## Typedefs
typedef uint64_t | bladerf_timestamp

## Macros
#define | BLADERF_PRIuTS PRIu64
#define | BLADERF_PRIxTS PRIx64
#define | BLADERF_SCNuTS SCNu64
#define | BLADERF_SCNxTS SCNx64

## Functions
API_EXPORT int CALL_CONV | bladerf_enable_module (struct bladerf *dev, bladerf_channel ch, bool enable)
API_EXPORT int CALL_CONV | bladerf_get_timestamp (struct bladerf *dev, bladerf_direction dir, bladerf_timestamp *timestamp)

## Typedef Documentation

## ◆ bladerf_timestamp

typedef uint64_t bladerf_timestamp

Timestamp, in ticks

A channel's timestamp typically increments at the sample rate.

See also
  Format macros for fprintf() and fscanf(): `BLADERF_PRIuTS`, `BLADERF_PRIxTS`, `BLADERF_SCNuTS`, `BLADERF_SCNxTS`

Definition at line 1793 of file libbladeRF.h.

## Macro Definition Documentation

## ◆ BLADERF_PRIuTS

#define BLADERF_PRIuTS PRIu64

printf format for timestamps in unsigned decimal

Definition at line 2021 of file libbladeRF.h.

## ◆ BLADERF_PRIxTS

#define BLADERF_PRIxTS PRIx64

printf format for timestamps in hexadecimal

Definition at line 2023 of file libbladeRF.h.

## ◆ BLADERF_SCNuTS

#define BLADERF_SCNuTS SCNu64

scanf format for timestamps in unsigned decimal

Definition at line 2025 of file libbladeRF.h.

## ◆ BLADERF_SCNxTS

#define BLADERF_SCNxTS SCNx64

scanf format for timestamps in hexadecimal

Definition at line 2027 of file libbladeRF.h.

## Function Documentation

## ◆ bladerf_enable_module()

API_EXPORT int CALL_CONV bladerf_enable_module | ( | struct bladerf * | dev,
|  | bladerf_channel | ch,
|  | bool | enable
| ) |  |

Enable or disable the RF front end of the specified direction.

RF front ends must always be enabled prior to streaming samples on the associated interface.

When a synchronous stream is associated with the specified channel, this will shut down the underlying asynchronous stream when `enable` = false.

When transmitting samples, be sure to provide ample time for TX samples reach the RF front-end before calling this function with `enable` = false. (This can be achieved easily when using metadata, as shown on this page.)

Parameters

  | dev | Device handle
  [in] | ch | Channel
  [in] | enable | true to enable, false to disable

Returns
  0 on success, value from Error codes list on failure

## ◆ bladerf_get_timestamp()

API_EXPORT int CALL_CONV bladerf_get_timestamp | ( | struct bladerf * | dev,
|  | bladerf_direction | dir,
|  | bladerf_timestamp * | timestamp
| ) |  |

Retrieve the specified stream's current timestamp counter value from the FPGA.

This function is only intended to be used to retrieve a coarse estimate of the current timestamp when starting up a stream. It should not be used as a means to accurately retrieve the current timestamp of individual samples within a running stream. The reasons for this are:

- The timestamp counter will have advanced during the time that the captured value is propagated back from the FPGA to the host
- The value retrieved in this manner is not tightly-coupled with specific sample positions in the stream.

When actively receiving a sample stream, instead use the bladerf_metadata::timestamp field (provided when using the BLADERF_FORMAT_SC16_Q11_META format) to retrieve the timestamp value associated with a block of samples. See the RX with metadata page for examples of this.

An example use-case of this function is to schedule an initial TX burst in a set of bursts:

- Configure and start a TX stream using the BLADERF_FORMAT_SC16_Q11_META format.
- Retrieve timestamp \(T\), a coarse estimate the TX's current timestamp via this function.
- Schedule the first burst, \(F\) to occur in the future: \(F = T + N\). Generally, adding \(N\) in tens to low hundreds of milliseconds is sufficient to account for timestamp retrieval overhead and stream startup.
- Schedule additional bursts relative to the first burst \(F\).

Examples of the above are shown on the TX with metadata page.

Parameters

  | dev | Device handle
  [in] | dir | Stream direction
  [out] | timestamp | Coarse timestamp value

Returns
  0 on success, value from Error codes list on failure