Operation

Methods used to read data from the connected TMF882X device.

Data Callback Functions

The TMF882X SDK returns data via a message structure passed to a user provided C function. This library allows the user to register callback functions that are called during the measurement operation.

The user has the option to register a generic message callback function, or specific functions based on message type.

setMessageHandler()

Call this method with a function that is called when any message is sent from the AMS sdk. The function passed into this method can be used to handle all messages instead of using the other handlers for specific message types.

The passed in function should be of type TMF882XMessageHandler, which is defined as:

typedef void (*TMF882XMessageHandler)(struct tmf882x_msg *msg);

This function accepts a parameter of type tmf882x_msg, which is defined as:

struct tmf882x_msg {
    union {
        struct tmf882x_msg_header       hdr;
        struct tmf882x_msg_error        err_msg;
        struct tmf882x_msg_histogram    hist_msg;
        struct tmf882x_msg_meas_results meas_result_msg;
        struct tmf882x_msg_meas_stats   meas_stat_msg;
        uint8_t msg_buf[TMF882X_MAX_MSG_SIZE];
    };
};

The type of the message is defined in msg->hdr.msg_id, and is one of the following types:

Type	Description
ID_MEAS_RESULTS	The results of a measurement - `meas_result_msg` is valid.
ID_MEAS_STATS	The measurement statistics - `meas_stat_msg` is valid.
ID_HISTOGRAM	The histogram of a measurement - `hist_msg` is valid.
ID_ERROR	An error occurred - `err_msg` is valid.

void setMessageHandler(TMF882XMessageHandler handler)

Parameter	Type	Description
handler	`TMF882XMessageHandler`	The message handler callback C function

setMeasurementHandler()

Call this method with a function that is called when measurement data is sent from the AMS sdk.

The passed in function should be of type TMF882XMeasurementHandler, which is defined as:

typedef void (*TMF882XMeasurementHandler)(struct tmf882x_msg_meas_results *message);

This function accepts a parameter of type tmf882x_msg_meas_results, which is defined as:

struct tmf882x_msg_meas_results {
    struct tmf882x_msg_header hdr;
    uint32_t result_num;         /* increments with every new bunch of results */
    uint32_t temperature;        /* temperature */
    uint32_t ambient_light;      /* ambient light level */
    uint32_t photon_count;       /* photon count */
    uint32_t ref_photon_count;   /* reference photon count */
    uint32_t sys_ticks;          /* system ticks */
    uint32_t valid_results;      /* number of valid results */
    uint32_t num_results;        /* number of results */
    struct tmf882x_meas_result results[TMF882X_MAX_MEAS_RESULTS];
};

The fields of the message structure are defined as:

field	Description
result_num	This is the result number reported by the device.
temperature	This is the temperature reported by the device (in Celsius)
ambient_light	This is the ambient light level reported by the device
photon_count	This is the photon count reported by the device
ref_photon_count	This is the reference channel photon count reported by the device
sys_ticks	This is the system tick counter (5MHz counter) reported by the device. This is used by the core driver to perform clock compensation correction on the measurement results.
valid_results	This is the number of targets reported by the device
num_results	This is the number of non-zero targets counted by the core driver
results	This is the list of measurement targets @ref struct tmf882x_meas_result

void setMeasurementHandler(TMF882XMeasurementHandler handler)

Parameter	Type	Description
handler	`TMF882XMeasurementHandler`	The message handler callback C function

setHistogramHandler()

Call this method with a function that is called when histogram data is sent from the AMS sdk.

The passed in function should be of type TMF882XHistogramHandler, which is defined as:

typedef void (*TMF882XHistogramHandler)(struct tmf882x_msg_histogram * message);

This function accepts a parameter of type tmf882x_msg_histogram, which is defined as:

struct tmf882x_msg_histogram {
    struct tmf882x_msg_header hdr;
    uint32_t capture_num;       /* matches the value of 'result_num' from measure result messages*/
    uint32_t sub_capture;       /* sub-capture measurement nubmer for time multiplexed measurements*/
    uint32_t histogram_type;    /* RAW, ELEC_CAL, etc */
    uint32_t num_tdc;           /* Number of histogram channels in this message */
    uint32_t num_bins;          /* length of histogram(s) for each channel */
    uint32_t bins[TMF882X_HIST_NUM_TDC][TMF882X_HIST_NUM_BINS];
};

The fields of the message structure are defined as:

field	Description
capture_num	This is the capture number that this set of histograms is associated with. The capture_num will match the `struct tmf882x_msg_meas_results::result_num`
sub_capture	This is the time-multiplexed sub-capture index of this set of histograms. For non-time-multiplexed measurements this value is always zero.
histogram_type	This is the histogram type identifier code `enum tmf882x_histogram_type`
num_tdc	This is the number of TDC histograms being published
num_bins	This is the number of bins in the histograms being published
bins	These are the histogram bin values for each TDC. There are two channels per TDC, the first channel histogram occupies bins `[0 : TMF882X_HIST_NUM_BINS/2 - 1]`, the 2nd channel occupies bins `[TMF882X_HIST_NUM_BINS/2 : @ref TMF882X_HIST_NUM_BINS - 1]`

void setHistogramHandler(TMF882XHistogramHandler handler)

Parameter	Type	Description
handler	`TMF882XHistogramHandler`	The message handler callback C function

setStatsHandler()

Call this method with a function that is called when measurement statistics data is sent from the AMS sdk.

The passed in function should be of type TMF882XStatsHandler, which is defined as:

typedef void (*TMF882XStatsHandler)(struct tmf882x_msg_meas_stats *message);

This function accepts a parameter of type tmf882x_msg_meas_stats, which is defined as:

struct tmf882x_msg_meas_stats {
    struct tmf882x_msg_header hdr;
    uint32_t capture_num;       /* matches the value of 'result_num' from measure result messages*/
    uint32_t sub_capture;       /* sub-capture measurement nubmer for time multiplexed measurements*/
    uint32_t tdcif_status;
    uint32_t iterations_configured;
    uint32_t remaining_iterations;
    uint32_t accumulated_hits;
    uint32_t raw_hits[TMF882X_HIST_NUM_TDC];
    uint32_t saturation_cnt[TMF882X_HIST_NUM_TDC];
};

The fields of the message structure are defined as:

field	Description
capture_num	This is the capture number that this set of histograms is associated with. The capture_num will match the `struct tmf882x_msg_meas_results::result_num`
sub_capture	This is the time-multiplexed sub-capture index of this set of histograms. For non-time-multiplexed measurements this value is always zero.
tdcif_status	This is the tdcif status reported by the device
iterations_configured	This is the iterations configured reported by the device
remaining_iterations	This is the remaining iterations reported by the device
accumulated_hits	This is the accumulated hits reported by the device
raw_hits	This is the raw hits reported by the device for each TDC
saturation_cnt	This is the saturation count reported by the device for each TDCd

void setStatsHandler(TMF882XStatsHandler handler)

Parameter	Type	Description
handler	`TMF882XStatsHandler`	The message handler callback C function

setErrorHandler()

Call this method with a function that is called when error information is sent from the AMS sdk.

The passed in function should be of type TMF882XErrorHandler, which is defined as:

typedef void (*TMF882XErrorHandler)(struct tmf882x_msg_error *message);

This function accepts a parameter of type tmf882x_msg_error, which is defined as:

struct tmf882x_msg_error {
    struct tmf882x_msg_header hdr;
    uint32_t err_code;
};

The fields of the message structure are defined as:

field	Description
err_code	This is the error code identifier

void setErrorHandler(TMF882XErrorHandler handler)

Parameter	Type	Description
handler	`TMF882XErrorHandler`	The message handler callback C function

Measurement Methods

startMeasuring()

Start measuring distance/data on the TMF882X device. This method returns after one measurement is performed.

Measurement data is returned in the provided measurement struct.

int startMeasuring(struct tmf882x_msg_meas_results results, uint32_t timeout = 0)

Parameter	Type	Description
results	`struct tmf882x_msg_meas_results`	The results of the measurement
timeout	`uint32_t`	[OPTIONAL] The time, in milliseconds, to take measurements. A value of zero [default value] indicates no timeout set
return value	`int`	The number of measurements taken (1), or -1 on error.

startMeasuring()

Start measuring distance/data on the TMF882X device. This method won't return until the measurement activity ends.

Measurement data is passed to the library user via a callback function, which is set using one of the setHandler() methods on this object.

Measurements continue, until one of the following conditions occurs:

The specified number of measurements took place (set via reqMeasurements)
The specified timeout value expires
The stopMeasuring() method was called in a Handler function.

This method won't start measuring if a measurement limit isn't set, a timeout isn't set and no callback handlers are not set.

This method returns the number of measurements taken

int startMeasuring(uint32_t reqMeasurements = 0, uint32_t timeout = 0)

Parameter	Type	Description
reqMeasurements	`uint32_t`	[OPTIONAL] The number of measurements desired. A value of zero [the default value] indicates no limit
timeout	`uint32_t`	[OPTIONAL] The time, in milliseconds, to take measurements. A value of zero [default value] indicates no timeout set
return value	`int`	The number of measurements taken, or -1 on error.

stopMeasuring()

Called to stop the device measuring loop. Normally called in a message handler function.

void stopMeasuring(void)

Parameter	Type	Description
None

setSampleDelay()

Set the delay used in the libraries sample loop used when processing samples/reading from the device.

void setSampleDelay(uint16_t delay)

Parameter	Type	Description
delay	`uint16_t`	The delay to use, in milli-seconds.

getSampleDelay()

Returns the current value of the library processing loop delay. The value is ib milliseconds..

uint16_t getSampleDelay(void)

Parameter	Type	Description
return value	`uint16_t`	The current delay, in milli-seconds.