Proximity Display Solution

/*
 * Solution Name: Distance-Based Relay & Display Control
 *
 * Description:
 * This embedded application uses LightRanger 3 Click, Relay 3 Click, 
 * and 8x8 G Click to measure the distance to an object and control relays 
 * and a display based on the measured distance. 
 * 
 * - If the average distance is <= 100 mm: Both relays turn ON.
 * - If the average distance is > 100 mm: Both relays turn OFF.
 * 
 * Distance measurements are averaged over multiple readings to reduce sensor noise 
 * and improve accuracy. The measured distance is displayed on the 8x8 G Click, 
 * and relay states are toggled automatically based on distance thresholds.
 *
 * The system utilizes the following Click boards:
 *   - LightRanger 3 Click: Measures the distance to a nearby object using 
 *     a laser sensor.
 *   - Relay 3 Click: Controls external devices based on distance thresholds.
 *   - 8x8 G Click: Displays the measured distance or clears the screen 
 *     when no action is needed.
 *
 * The `application_init` function initializes the logger and all Click boards, 
 * ensuring proper startup conditions. Any initialization failure is logged, 
 * and the system halts.
 *
 * The `application_task` function continuously measures the distance, 
 * calculates the average distance, updates the display, and toggles the relays 
 * based on the distance threshold.
 *
 * Hardware Setup:
 *   - MIKROBUS_1: 8x8 G Click
 *   - MIKROBUS_2: Relay 3 Click
 *   - MIKROBUS_3: LightRanger 3 Click
 *
 * Key Features:
 *   - Continuous distance monitoring with real-time relay control.
 *   - Multi-sample averaging to reduce sensor reading noise.
 *   - Distance display with automatic clearing when no action is needed.
 *   - UART logging for measurement data and system events.
 *   - Automatic relay switching based on distance threshold.
 *
 * Development Environment:
 *   - [NECTO Studio](https://www.mikroe.com/necto)
 *   - [mikroSDK v2.0](https://www.mikroe.com/mikrosdk) framework
 *   - MIKROE [Click boards](https://www.mikroe.com/click-boards) Add-ons
 *
 * Author: Branko Jaksic
 * Date: 2025
 */

// ------------------------------------------------------------------- INCLUDES
#include "log.h"
#include "board.h"
#include "c8x8g.h"
#include "relay3.h"
#include "lightranger3.h"
#include "conversions.h"

// ------------------------------------------------------------------ VARIABLES
static log_t logger;
static c8x8g_t c8x8g;
static relay3_t relay3;
static lightranger3_t lightranger3;

static int case_both_relays_switch = 0;

// ---------------------------------------------- PRIVATE FUNCTION DECLARATIONS
/**
 * @brief Toggle Both Relays On/Off
 * 
 * This function toggles the state of both relays connected to the Relay 3 Click board. 
 * It uses a state switch (`case_both_relays_switch`) to alternate between turning both 
 * relays ON and OFF. 
 * 
 * - When `case_both_relays_switch` is `0`, both relays are turned ON, and a message is 
 *   logged via UART.
 * - When `case_both_relays_switch` is `1`, both relays are turned OFF, and a corresponding 
 *   message is logged.
 * 
 * The function updates the `case_both_relays_switch` variable to track the current state, 
 * flipping its value between `0` and `1` on each call.
 * 
 * This function can be used in scenarios where relays need to be toggled at regular intervals 
 * or based on specific conditions (e.g., distance threshold crossing).
 * 
 * @note The function relies on a global variable `case_both_relays_switch` to manage state.
 */
static void case_both_relays ( );

// ----------------------------------------------- PUBLIC FUNCTION DECLARATIONS

/**
 * @brief Initializes the LightRanger 3 Click board.
 *
 * Configures the LightRanger 3 Click board and performs device initialization. 
 * If the sensor fails to initialize, the function logs an error and halts
 * execution.
 *
 * @note The LightRanger 3 Click is connected to MIKROBUS_4.
 */
void initialize_light_ranger( void );

/**
 * @brief Initializes the Relay 3 Click board.
 *
 * Configures the Relay 3 Click board and performs device initialization. 
 * If the Relay fails to initialize, the function logs an error and halts
 * execution.
 *
 * @note The Relay 3 Click is connected to MIKROBUS_3.
 */
void initialize_relay_3( void );

/**
 * @brief Initializes the 8x8 G Click board.
 *
 * Configures the 8x8 G Click board and performs device initialization. 
 * If the 8x8 G Click fails to initialize, the function logs an error and halts
 * execution.
 *
 * @note The 8x8 G Click is connected to MIKROBUS_2.
 */
void initialize_8x8_g( void );

/**
 * @brief Display Distance on 8x8 G Click.
 *
 * Converts the measured distance to a string and displays it on the 8x8 G Click board.
 * The distance is shown in millimeters (e.g., "123mm").
 * 
 * @param[in] distance  The measured distance value in millimeters.
 */
void display_distance_on_8x8_g( uint16_t distance );

/**
 * @brief Clears the display on 8x8 G Click.
 *
 * Clears the display and shows a message.
 */
void clear_display_on_8x8_g( void );

/**
 * @brief Measures and logs the distance using the LightRanger 3 Click.
 *
 * Takes a single distance measurement, retrieves the distance value,
 * and logs it via UART. This function is useful for quick,
 * real-time distance readings.
 */
void measure_and_log_distance( void );

// ------------------------------------------------------ APPLICATION FUNCTIONS
static void case_both_relays ( )
{
    if ( case_both_relays_switch == 0 )
    {
        relay3_relay_on( &relay3, RELAY3_BOTH_RELAYS );
        log_printf( &logger, "   Both relays ON.   \r\n" );

        case_both_relays_switch++;
    }
    else if ( case_both_relays_switch == 1 )
    {
        relay3_relay_off( &relay3, RELAY3_BOTH_RELAYS );
        log_printf( &logger, "   Both relays OFF.   \r\n" );

        case_both_relays_switch--;
    }
}

void application_init( void ) 
{
    log_cfg_t log_cfg;

    // Logger initialization
    LOG_MAP_USB_UART( log_cfg );
    log_init( &logger, &log_cfg );
    log_info( &logger, "Application Init" );

    // initialize_button_play();
    initialize_light_ranger();
    initialize_relay_3();
    initialize_8x8_g();

    log_info( &logger, "Initialization Complete, Starting Application Task" );
}

void initialize_light_ranger( void )
{
    lightranger3_cfg_t lightranger3_cfg;

    lightranger3_cfg_setup( &lightranger3_cfg );
    LIGHTRANGER3_MAP_MIKROBUS( lightranger3_cfg, MIKROBUS_3 );
    lightranger3_init( &lightranger3, &lightranger3_cfg );

    if ( lightranger3_device_init( &lightranger3 ) != 0 ) 
    {
        log_error( &logger, "LightRanger Click initialization failed!" );
        for ( ; ; );  // Halt execution
    }

    log_info( &logger, "LightRanger Click initialized successfully." );
}

void initialize_relay_3( void ) {
    relay3_cfg_t relay3_cfg;

    relay3_cfg_setup( &relay3_cfg );
    RELAY3_MAP_MIKROBUS( relay3_cfg, MIKROBUS_2 );
    relay3_init( &relay3, &relay3_cfg );
}

void initialize_8x8_g( void ) {
    c8x8g_cfg_t c8x8g_cfg;

    c8x8g_cfg_setup( &c8x8g_cfg );
    C8X8G_MAP_MIKROBUS( c8x8g_cfg, MIKROBUS_1 );
    err_t init_flag  = c8x8g_init( &c8x8g, &c8x8g_cfg );
    if ( init_flag == SPI_MASTER_ERROR ) {
        log_info( &logger, " Application Init Error. " );
        log_info( &logger, " Please, run program again... " );

        for ( ; ; );
    }

    c8x8g_default_cfg ( &c8x8g );
}

void display_distance_on_8x8_g( uint16_t distance )
{
    char distance_str[ 5 ];
    uint16_to_str(distance, distance_str);

    // Show distance in mm (up to 9999 mm)
    c8x8g_display_string( &c8x8g, distance_str );
}

void clear_display_on_8x8_g( void )
{
    c8x8g_display_byte( &c8x8g, ' ' );
}

void application_task( void )
{
    // Continuously measure distance
    uint32_t distance_sum = 0;
    uint8_t num_measurements = 5;

    for ( uint8_t i = 0; i < num_measurements; i++ ) 
    {
        lightranger3_take_single_measurement( &lightranger3 );
        distance_sum += lightranger3_get_distance( &lightranger3 );
        Delay_ms( 100 ); // Small delay between measurements
    }

    uint16_t average_distance = ( uint16_t )( distance_sum / num_measurements );
    log_printf( &logger, "Average Distance: %u mm\r\n", average_distance );

    // Display the distance on 8x8 G Click
    display_distance_on_8x8_g( average_distance );

    // Control relays based on distance threshold
    if ( average_distance <= 100 && case_both_relays_switch == 0 ) 
    {
        log_printf( &logger, "Distance <= 100 mm! Turning both relays ON.\r\n" );
        case_both_relays();
    } 
    else if ( average_distance > 100 && case_both_relays_switch == 1 ) 
    {
        log_printf( &logger, "Distance > 100 mm! Turning both relays OFF.\r\n" );
        case_both_relays();
    }
    else {
        // Clear display.
        clear_display_on_8x8_g();
    }
}

void measure_and_log_distance( void )
{
    lightranger3_take_single_measurement( &lightranger3 );
    uint16_t distance = lightranger3_get_distance( &lightranger3 );

    log_printf( &logger, "Distance: %u mm\r\n", distance );
}

int main( void ) 
{
    #ifdef PREINIT_SUPPORTED
    preinit();
    #endif

    application_init();

    while ( 1 ) 
    {
        application_task();
    }

    return 0;
}