LED.h

Go to the documentation of this file.

/*
 * Copyright (c) 2016-2021, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/*!*****************************************************************************
 *  @file       LED.h
 *
 *  @brief      LED driver
 *
 *  The LED driver is provided for easy access to common LED functionality.
 *  All functionality can be replicated using the GPIO.h and PWM.h APIs.
 *
 *  @anchor ti_drivers_LED_Synopsis
 *  # Synopsis #
 *
 *  @code
 *  #include <ti/drivers/apps/LED.h>
 *
 *  LED_Handle handle;
 *  LED_Params ledParams;
 *
 *  // Assume our LED is configured to be a PWM LED
 *  LED_Params_init(&ledParams);
 *  ledHandle = LED_open(CONFIG_LED0, &ledParams);
 *
 *  // Turn on, set brightness, and blink
 *  LED_setOn(handle, 80);
 *  LED_startBlinking(handle, 500, LED_BLINK_FOREVER);
 *
 *  LED_setOff(handle);
 *  LED_close(handle);
 *
 *  @endcode
 *
 *  @anchor ti_drivers_LED_Examples
 *  ## Examples #
 *
 *  * @ref ti_drivers_LED_Examples_config_array "Generic Configuration"
 *  * @ref ti_drivers_LED_Examples_gpio_config "GPIO Configuration"
 *  * @ref ti_drivers_LED_Examples_pwm_led "PWM Mode"
 *
 *  # Operation #
 *  LED driver simplifies using an LED (may be GPIO or PWM controlled)
 *  available on board and supports following operations -
 *
 *      1. To Turn ON/OFF
 *      2. Blink with requested delay, stop when requested
 *      3. Vary brightness (can only be done to a PWM controlled LED)
 *      4. Toggle
 *
 *  There are also APIs to open and close an LED handle and also one to get
 *  current state of a LED. User can request to set a LED into particular state
 *  while opening itself i.e. to start blink as part of LED_open() call.
 *
 *  LED_init() must be called before using LED_open().
 *
 *  ## Defining #LED_Config, #LED_Object and #LED_HWAttrs #
 *  To use the LED driver, an application has to indicate how many LEDs it
 *  wants to operate, of what type (PWM or GPIO controlled), and which GPIO or
 *  PWM to index for each LED.
 *
 *  Each structure must be defined by the application. The following
 *  example is for an MSP432P401R platform in which four LEDs are available
 *  on board.
 *  The following declarations are placed in "ti_drivers_config.c".
 *  How the gpio indices are defined is detailed in the next section.
 *
 *  ### LED_config structures #
 *  @anchor ti_drivers_LED_Examples_config_array
 *  "ti_drivers_config.c"
 *  @code
 *  #include <ti/drivers/apps/LED.h>
 *
 *  LED_Object LED_object[4];
 *
 *  const LED_HWAttrs LED_hwAttrs[4] = {
 *          {
 *              .index = CONFIG_LED1,
 *              .type  = LED_GPIO_CONTROLLED
 *          },
 *          {
 *              .index = CONFIG_LED_RED,
 *              .type  = LED_GPIO_CONTROLLED
 *          },
 *          {
 *              .index = CONFIG_NA_GPIO_PWMLED,
 *              .type  = LED_PWM_CONTROLLED
 *          },
 *          {
 *              .index = CONFIG_NA_GPIO_PWMLED,
 *              .type  = LED_PWM_CONTROLLED
 *          }
 *  };
 *
 *  const LED_Config LED_config[] = {
 *      {
 *          .object =  &LED_object[0],
 *          .hwAttrs = &LED_hwAttrs[0],
 *      },
 *      {
 *          .object =  &LED_object[1],
 *          .hwAttrs = &LED_hwAttrs[1],
 *      },
 *      {
 *          .object =  &LED_object[2],
 *          .hwAttrs = &LED_hwAttrs[2],
 *      },
 *      {
 *          .object =  &LED_object[3],
 *          .hwAttrs = &LED_hwAttrs[3],
 *      }
 *  };
 *
 *  uint32_t LED_count = 4;
 *
 *  @endcode
 *
 *  ##Setting up a GPIO controlled LED #
 *  The following code snippet shows how a GPIO pin controlling an LED is
 *  configured. The index the user provides to LED_open() corresponds to an
 *  entry in the #GPIO_PinConfig array which will source the LED. It is the
 *  user's responsibility to ensure that the pin is configured properly in the
 *  pin array. Typically this means configuring the pin as an output.
 *
 *  ### GPIO controlled LED #
 *  @anchor ti_drivers_LED_Examples_gpio_config
 *
 *  The following definitions are in
 *  "ti_drivers_config.h" and "ti_drivers_config.c" respectively. This
 *  example uses GPIO pins 1.0 and 2.0 which control LED1 and RED LED on
 *  LaunchPad respectively. In addition to the structures shown below, the
 *  other GPIO configuration data must exist. See @ref GPIO.h.
 *
 *  "ti_drivers_config.h"
 *  @code
 *  #define CONFIG_LED1         0
 *  #define CONFIG_LED_RED      1
 *  @endcode
 *
 *  "ti_drivers_config.c"
 *  @code
 *  #include <ti/drivers/GPIO.h>
 *  GPIO_PinConfig gpioPinConfigs[] = {
 *      GPIOMSP432_P1_0 | GPIO_CFG_OUT_STD | GPIO_CFG_OUT_STR_HIGH | GPIO_CFG_OUT_LOW,
 *      GPIOMSP432_P2_0 | GPIO_CFG_OUT_STD | GPIO_CFG_OUT_STR_HIGH | GPIO_CFG_OUT_LOW,
 *  }
 *
 *  @endcode
 *
 *  ## Configuring a PWM controlled LED #
 *  The LED driver allows for an LED to be driven by the PWM driver. This allows
 *  the user to set a brightness level in addition to the other LED features.
 *  The user must specify in the #LED_HWAttrs of each #LED_Config entry which
 *  #PWM_Config the LED instance is allowed to use. LED instances cannot share
 *  a PWM instance.
 *
 *  The user may specify the period of the PWM signal in the #LED_Params passed
 *  to LED_open(). This is not to be confused with #LED_Params.blinkPeriod
 *  which specifies the default blink period.
 *
 *  ### Opening a PWM LED #
 *  @anchor ti_drivers_LED_Examples_pwm_led
 *
 *  We will borrow the 3rd LED_config entry from the
 *  @ref ti_drivers_LED_Examples_config_array
 *
 *  In "ti_drivers_config.h"
 *  @code
 *  #define CONFIG_LED0     0
 *  @endcode
 *
 *  In application code:
 *  @code
 *  #include <ti/drivers/apps/LED.h>
 *
 *  LED_Handle LEDHandle;
 *  LED_Params ledParams;
 *
 *  LED_Params_init(&ledParams);
 *  ledParams.pwmPeriod = 100; // 0.1 ms period
 *  ledParams.blinkPeriod = 500; // LED will toggle twice a second
 *  ledParams.setState = LED_STATE_BLINKING; // Start LED blink on open
 *  ledHandle = LED_open(CONFIG_LED0, &ledParams); // Open the first LED_Config
 *
 *  // Turn on at half brightness level
 *  LED_setOn(ledHandle, 50);
 *  @endcode
 *
 *******************************************************************************
 */

#ifndef ti_drivers_LED__include
#define ti_drivers_LED__include

#include <stdint.h>
#include <stdbool.h>

/* Driver Header files */
#include <ti/drivers/GPIO.h>
#include <ti/drivers/PWM.h>
#include <ti/drivers/dpl/ClockP.h>

#ifdef __cplusplus
extern "C" {
#endif

#define LED_BRIGHTNESS_MAX 100U /* Max brightness in % is 100%*/
#define LED_BRIGHTNESS_MIN 0U   /* Max brightness in % is 0%*/

#define LED_ON  1U
#define LED_OFF 0U

#define LED_BLINK_FOREVER 0xFFFF

/* Number of user defined LED configurations */
extern const uint_least8_t LED_count;

typedef enum
{
    LED_NONE = 0,
    LED_GPIO_CONTROLLED,
    LED_PWM_CONTROLLED
} LED_Type;

typedef enum
{
    LED_STATE_OFF = 0,
    LED_STATE_ON,
    LED_STATE_BLINKING
} LED_State;

typedef struct
{
    void *object;
    void const *hwAttrs;
} LED_Config;

typedef LED_Config *LED_Handle;

typedef struct
{
    uint_least8_t index; 
    LED_Type type;       /*<! GPIO (binary) or PWM (dimmable) control */
} LED_HWAttrs;

typedef struct
{
    uint32_t pwmPeriod;        
    PWM_Handle pwmHandle;      
    ClockP_Handle clockHandle; 
    ClockP_Struct clock;       
    LED_State state;           
    LED_State rawState;        
    LED_Type ledType;          
    uint8_t brightness;        
    uint_least8_t gpioIndex;   
    uint16_t togglePeriod;     
    uint16_t blinkCount;       
} LED_Object;

typedef struct
{
    uint32_t pwmPeriod;   
    uint16_t blinkPeriod; 
    uint8_t brightness;   
    LED_State setState;   
} LED_Params;

extern void LED_close(LED_Handle ledHandle);

extern LED_State LED_getState(LED_Handle ledHandle);

extern void LED_init(void);

LED_Handle LED_open(uint_least8_t index, LED_Params *params);

extern void LED_Params_init(LED_Params *params);

extern bool LED_setBrightnessLevel(LED_Handle ledHandle, uint8_t level);

extern bool LED_setOff(LED_Handle ledHandle);

extern bool LED_setOn(LED_Handle ledHandle, uint8_t brightness);

extern void LED_startBlinking(LED_Handle ledHandle, uint16_t blinkPeriod, uint16_t blinkCount);

extern void LED_stopBlinking(LED_Handle ledHandle);

extern void LED_toggle(LED_Handle ledHandle);

extern void LED_write(LED_Handle ledHandle, bool value);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_LED__include */