Data Readout

The device provides a stream of packets (see Output Data Format) that are read in batches with ndigo_read().

ndigo_read() requires ndigo_read_in as configuration.

ndigo_read() stores the read batch in a ndigo_read_out struct.

Every packet needs to be acknowledged before its memory location can be used again by the Ndigo5G device.

A typical workflow in an application would be:

Instead of manually acknowledging each batch, each read batch of data can be automatically acknowledged by setting ndigo_read_in::acknowledge_last_read to true.

The following example highlights the workflow. A complete coding example can be found on github.com/cronologic-de/ndigo5g_babel or in Code example.

ndigo_read_in read_config;
read_config.acknowledge_last_read = true;
ndigo_read_out read_data;

status = ndigo_read(device, &read_config, &read_data)
if (status != ndigo_OK) {
    // handle errors of the call to timetagger4_read
}
else if (read_data.error_code != ndigo_READ_OK)
{
    // handle read errors, e.g., empty packets
}
else
{
    volatile ndigo_packet *p = read_data.first_packet;
    while (p <= read_data.last_packet)
    {

        /* process data */

        p = ndigo_next_packet(p);
    }
}
int ndigo_read(ndigo_device *device, ndigo_read_in *in, ndigo_read_out *out)

Reads packets.

Returns a pointer to an array of captured data in out. The result contains any number of packets of type ndigo_packet.

Parameters:

  • device – [in] Pointer to the device from which to read.

  • in – [in] Pointer to the struct that configures the read call.

  • out – [out] Pointer to a struct in which the read-out will be stored.

Returns:

A status code.

int ndigo_acknowledge(ndigo_device *device, volatile ndigo_packet *packet)

Acknowledge data.

Acknowledge all data up to the packet provided as the input parameter. This is mandatory if ndigo_read() was called with ndigo_read_in::acknowledge_last_read set to false.

This feature allows freeing up partial host memory early if there will be no call to ndigo_read() anytime soon.

It also allows to keep data over multiple calls to ndigo_read, avoiding unnecessary copying of data.

Attention

After acknowledging a packet it becomes immediately invalid. It is immediately unsafe to attempt accessing its content.

Parameters:

  • device – [in] Pointer to the device.

  • packet – [in] Pointer to a packet. All packets up to this one will be acknowledged.

Returns:

A status code.

struct ndigo_read_in

Parameters for ndigo_read().

Public Members

ndigo_bool_t acknowledge_last_read

Automatic acknowledgement of packets.

If set, ndigo_read() automatically acknowledges packets from the last read.

struct ndigo_read_out

Parameters for ndigo_read().

Public Members

volatile ndigo_packet *first_packet

Pointer to the first packet that was captured by the call of ndigo_read().

volatile ndigo_packet *last_packet

Address of the header of the last packet in the buffer.

int error_code

Read error code.

Will be one of the following:

NDIGO_READ_OK 0

No read error occurred.

NDIGO_READ_NO_DATA 1

Read did not yield any data.

NDIGO_READ_INTERNAL_ERROR 2

Error in buffer handling. The device has to be re-initialized.

NDIGO_READ_TIMEOUT 3

Currently not used.

const char *error_message

Corresponding error message.

int ndigo_process_tdc_packet(ndigo_device *device, volatile ndigo_packet *packet)

Calculate the exact TDC packet timestamp.

Call on a TDC packet (that is, ndigo_packet::channel = 4) to update the timestamp of the packet with a more accurate value.

Attention

If called more than once on a packet, the timestamp will be invalid.

Parameters:

  • device – [in] A pointer to the device.

  • packet – [out] Pointer to a TDC packet in which to update the timestamp.

Returns:

A status code.

short ndigo_convert_value(ndigo_device *device, int channel, short val, int outputModeFrom, int outputModeTo)

Convert one output data type to another.

Parameters:

  • device – [in] Pointer to the device.

  • channel – [in] Source channel of the data.

  • val – [in] Value to convert.

  • outputModeFrom – [in] Original output mode .

  • outputModeTo – [in] New output mode .

Returns:

The converted value.

ndigo_next_packet(current) ((volatile ndigo_packet *)(((int64_t)(current)) + (((current)->type & 128 ? 0 : (current)->length) + 2) * 8))

Macro that gets the address of the next packet after the current packet.

The validity of the address must be checked. 

int status = ndigo_read(device, &in, &out);
if (status == NDIGO_OK && out.first_packet != nullptr) {
    volatile ndigo_packet *packet = ndigo_next_packet(out.first_packet);
    while (packet <= out.last_packet) { // while packet address is valid
        // do stuff
        volatile ndigo_packet *next_packet = ndigo_next_packet(packet);
        packet = next_packet;
    }
}