AFBR-S50 API Reference Manual v1.5.6
AFBR-S50 Time-of-Flight Sensor SDK for Embedded Software
Loading...
Searching...
No Matches
01_simple_example_with_hal_self_test.c
/*************************************************************************/
#include "argus.h"
// additional #includes ...
#include "argus_hal_test.h"
/*!***************************************************************************
* @brief Creates and initializes a new device instance.
*
* @param slave The SPI slave identifier number that is passed to the S2PI
* layers by the API whenever it calls a function.
*
* @return The pointer to the handle of the created device instance. Used to
* identify the calling instance in case of multiple devices.
*****************************************************************************/
static argus_hnd_t* InitializeDevice(s2pi_slave_t slave)
{
/* The API module handle that contains all data definitions that is
* required within the API module for the corresponding hardware device.
* Every call to an API function requires the passing of a pointer to this
* data structure. */
HandleError(device ? STATUS_OK : ERROR_FAIL, true, "Argus_CreateHandle failed!");
/* Initialize the API with the dedicated default measurement mode.
* This implicitly calls the initialization functions
* of the underlying API modules.
*
* The second parameter is stored and passed to all function calls
* to the S2PI module. This piece of information can be utilized in
* order to determine the addressed SPI slave and enabled the usage
* of multiple devices on a single SPI peripheral.
*
* Also note the #Argus_InitMode alternative that uses a third
* parameter to choose the measurement mode: see the #argus_mode_t
* enumeration for more information on available measurement modes. */
status_t status = Argus_Init(device, slave);
HandleError(status, true, "Argus_Init failed!");
/* Adjust additional configuration parameters by invoking the dedicated API methods.
* Note: The maximum frame rate is limited by the amount of data sent via UART.
* See #PrintResults function for more information. */
status = Argus_SetConfigurationFrameTime(device, 100000); // 0.1 second = 10 Hz
HandleError(status, true, "Argus_SetConfigurationFrameTime failed!");
return device;
}
/*!***************************************************************************
* @brief Triggers a measurement cycle in blocking manner.
*
* @param device The pointer to the handle of the calling API instance. Used to
* identify the calling instance in case of multiple devices.
*
* @param res The pointer to the results data structure where the final
* measurement results are stored.
*****************************************************************************/
static void TriggerMeasurementBlocking(argus_hnd_t * device, argus_results_t * res)
{
/* Triggers a single measurement.
*
* Note that due to the laser safety algorithms, the method might refuse
* to restart a measurement when the appropriate time has not been elapsed
* right now. The function returns with status #STATUS_ARGUS_POWERLIMIT and
* the function must be called again later. Use the frame time configuration
* in order to adjust the timing between two measurement frames.
*
* The callback can be null for the trigger function if the #Argus_GetStatus
* function is used to await the measurement cycle to finish. Otherwise, the
* callback should be set to receive the measurement ready event. See the
* advanced example on how to use the callback. */
do
{
HandleError(status, false, "Argus_TriggerMeasurement failed!");
/* Wait until measurement data is ready by polling the #Argus_GetStatus
* function until the status is not #STATUS_BUSY any more. Note that
* the actual measurement is performed asynchronously in the background
* (i.e. on the device, in DMA transfers and in interrupt service routines).
* Thus, one could do more useful stuff while waiting here... */
do
{
}
while (status == STATUS_BUSY);
HandleError(status, false, "Waiting for measurement data ready (Argus_GetStatus) failed!");
/* Evaluate the raw measurement results by calling the #Argus_EvaluateData function. */
status = Argus_EvaluateData(device, res);
HandleError(status, false, "Argus_EvaluateData failed!");
}
/*!***************************************************************************
* @brief Prints measurement results via UART.
*
* @details Prints some measurement data via UART in the following format:
*
* ```
* 123.456789 s; Range: 123456 mm; Amplitude: 1234 LSB; Quality: 100; Status: 0
* ```
*
* @param res A pointer to the latest measurement results structure.
*****************************************************************************/
static void PrintResults(argus_results_t const * res)
{
/* Print the recent measurement results:
* 1. Time stamp in seconds since the last MCU reset.
* 2. Range in mm (converting the Q9.22 value to mm).
* 3. Amplitude in LSB (converting the UQ12.4 value to LSB).
* 4. Signal Quality in % (100% = good signal).
* 5. Status (0: OK, <0: Error, >0: Warning.
*
* Note: Sending data via UART creates a large delay which might prevent
* the API from reaching the full frame rate. This example sends
* approximately 80 characters per frame at 115200 bps which limits
* the max. frame rate of 144 fps:
* 115200 bps / 10 [bauds-per-byte] / 80 [bytes-per-frame] = 144 fps */
print("%4d.%06d s; Range: %5d mm; Amplitude: %4d LSB; Quality: %3d; Status: %d\n",
res->TimeStamp.sec,
res->Bin.Range / (Q9_22_ONE / 1000),
res->Status);
}
/*!***************************************************************************
* @brief Prints information about the initialized devices.
*
* @param device The pointer to the device handler.
*****************************************************************************/
static void PrintDeviceInfo(argus_hnd_t * device)
{
/* Print some information about current API and connected device. */
const uint32_t value = Argus_GetAPIVersion();
const uint8_t a = (uint8_t)((value >> 24) & 0xFFU);
const uint8_t b = (uint8_t)((value >> 16) & 0xFFU);
const uint8_t c = (uint8_t)(value & 0xFFFFU);
const uint32_t id = Argus_GetChipID(device);
const char * m = Argus_GetModuleName(device);
print("\n##### AFBR-S50 API - Simple Example ###########################\n"
" API Version: v%d.%d.%d\n"
" Chip ID: %d\n"
" Module: %s\n"
"###############################################################\n\n",
a, b, c, id, m);
}
/*!***************************************************************************
* @brief Application entry point for the simple example.
*
* @details The main function of the simple example, called after startup code
* and hardware initialization.
*
* This function will never be exited!
*****************************************************************************/
void main(void)
{
HardwareInit(); // defined elsewhere
/* Running a sequence of test in order to verify the HAL implementation. */
HandleError(status, true, "HAL Implementation verification failed on SPI_SLAVE!");
/* Instantiate and initialize the device handlers. */
argus_hnd_t * device = InitializeDevice(SPI_SLAVE);
/* Print a device information message. */
PrintDeviceInfo(device);
/* The program loop ... */
for (;;)
{
/* The measurement data structure. */
/* Trigger a measurement for the current device. */
TriggerMeasurementBlocking(device, &res);
/* Use the obtain results, e.g. print via UART. */
PrintResults(&res);
}
}
int main(void)
Application entry point.
Definition main.c:48
This file is part of the AFBR-S50 API.
Tests for the AFBR-S50 API hardware abstraction layer.
char const * Argus_GetModuleName(argus_hnd_t *hnd)
Gets the name string of the module.
status_t Argus_Init(argus_hnd_t *hnd, s2pi_slave_t spi_slave)
Initializes the device with default measurement mode.
uint32_t Argus_GetChipID(argus_hnd_t *hnd)
Gets the unique identification number of the chip.
argus_hnd_t * Argus_CreateHandle(void)
Creates a new device data handle object to store all internal states.
struct argus_hnd_t argus_hnd_t
Definition argus_def.h:284
int32_t s2pi_slave_t
Definition argus_api.h:67
uint32_t Argus_GetAPIVersion(void)
Gets the version number of the current API library.
status_t Argus_SetConfigurationFrameTime(argus_hnd_t *hnd, uint32_t value)
Sets the frame time to a specified device.
#define UQ12_4_ONE
Definition fp_def.h:237
#define Q9_22_ONE
Definition fp_def.h:547
status_t print(const char *fmt_s,...)
A printf-like function to print formatted data to an debugging interface.
Definition sci_log.c:106
status_t Argus_EvaluateData(argus_hnd_t *hnd, argus_results_t *res)
Evaluates measurement data from the raw sensor readout data.
status_t Argus_TriggerMeasurement(argus_hnd_t *hnd, argus_measurement_ready_callback_t cb)
Triggers a single measurement frame asynchronously.
status_t Argus_GetStatus(argus_hnd_t *hnd)
Checks the state of the device/driver.
int32_t status_t
Type used for all status and error return values.
Definition argus_status.h:70
@ STATUS_BUSY
Definition argus_status.h:89
@ STATUS_ARGUS_POWERLIMIT
Definition argus_status.h:167
@ STATUS_OK
Definition argus_status.h:80
@ ERROR_FAIL
Definition argus_status.h:95
status_t Argus_VerifyHALImplementation(s2pi_slave_t spi_slave)
Executes a series of tests in order to verify the HAL implementation.
Definition argus_hal_test.c:103
static status_t status
Definition argus_xtalk_cal_cli.c:140
void HandleError(status_t status, bool stop, char const *msg)
A callback function from the example code whenever an error occurs.
Definition main.c:62
#define SPI_SLAVE
Definition examples.h:102
uint8_t SignalQuality
Definition argus_res.h:87
q9_22_t Range
Definition argus_res.h:75
uq12_4_t Amplitude
Definition argus_res.h:81
The measurement results data structure.
Definition argus_res.h:216
ltc_t TimeStamp
Definition argus_res.h:225
status_t Status
Definition argus_res.h:221
argus_results_bin_t Bin
Definition argus_res.h:269
uint32_t usec
Definition time.h:77
uint32_t sec
Definition time.h:73