led.h

Go to the documentation of this file.

#ifndef DRIVER_LED_H
#define DRIVER_LED_H
/**********************************************************************/
/*
 * Copyright (c) 2014, Jetro AS
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * 2. 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.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONRIBUTORS ``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 AUTHOR 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.
 *
 * This file is part of the EVE platform.
 */

/**
 * \file
 * @brief Driver for Leds
 *
 * @author AMO, Jetro as
 */ /******************************************************************/

#include <core/mwork.h>

/** \defgroup led LED driver
 *  \ingroup abstract
 *  \{
 *
 * Totally 32 LEDs can be updated.
 * Functionality included if LED_ENABLED is set true:
 * - Initialization of led function
 * - Setting of LEDs, off, on or flashing.
 *   (several flashing pattern can be defined).
 * - Led counting (number of count and timing is selectable).
 *
 * if flashing functions are wanted LED_FLASHING_ENABLED must be set true and
 * the number of flashing pattern must be defined by NUMBER_OF_FLASHING_PATTERN.
 * Each flashing pattern must be defined in table "struct led_flash_t LedFlashing[]" in Board.c.
 * if counting function is wanted LED_COUNTING_ENABLED must be set true.
 *
 * Output function for setting each led is based of the inline code UpdateLeds().
 *
 */

/***********************************************************************
 * Global defines
***********************************************************************/

/** Indexes of the Time array in the struct led_counting_t */
enum {
  COUNTING_ON,              //!< Time in processor ticks LED(s) is on
  COUNTING_OFF,             //!< Time in processor ticks LED(s) is off
  COUNTING_PAUSE,           //!< Pause time in processor ticks between flashing series
  NUMBER_OF_COUNTING_TIMES  //!< Gives array size
};

/** Parameters for LED counting */
struct led_counting_t
{
  uint16_t Time[NUMBER_OF_COUNTING_TIMES]; //!< 1/1.024 ms resolution, use MWORK_MSEC(). If Time[COUNTING_PAUSE] = 0, the flashing is stopped after one sequence
  uint8_t Count;                           //!< Number of flashes per flashing serie
  bool Invert;                             //!< If TRUE, the flashing is inverted (ON<->OFF)
};

/** Constant flashing parameters */
struct led_flash_t
{
  uint16_t OnTime;                          //!< Time the LED is on, 1/1.024 ms resolution, use MWORK_MSEC()
  uint16_t OffTime;                         //!< Time the LED is off, 1/1.024 ms resolution, use MWORK_MSEC()
};

/** Input parameters for LedSet() function */
enum {
  LED_OFF             = 0x00,  //!< Set LED(s) off
  LED_ON              = 0x01,  //!< Set LED(s) on
  LED_FLASHING        = 0x02,  //!< Set LED(s) to constant flashing
  LED_INVERT_FLASHING = 0x80,  //!< Set LED(s) to constant invert flashing
};

/**
  * \name Functions called from application programs
  * \{
  */
/**********************************************************************/
/**
 * @brief Initialize LED driver.
 * Must be called before LedSet() or LedCounting() can be called.
 ***********************************************************************/
extern void LedInit(void);

/**********************************************************************/
/**
 * @brief Sets LED(s) function (on/off/flash).
 *
 * @param Leds      Each bit position (0-31) represent a LED.
 *                  New function can be set for several Leds in one
 *                  function call.
 *                  If no LEDs are already flashing, the flashing
 *                  sequence is restarted.
 *
 * @param Function  Select LED functionality:
 *                    LED_OFF
 *                    LED_ON
 *                    LED_FLASHING + type of LED flashing pattern (0 to max 99)
 *                    + optional LED_INVERT_FLASHING if inverted flashing
 *                      pattern is wanted
 ***********************************************************************/
extern void LedSet(uint32_t Leds, uint32_t Function);

/**********************************************************************/
/**
 * @brief Sets LED(s) to counting function.
 *
 * @param Leds      Each bit position (0-31) represent a LED.
 *                  New function can be set for several Leds in one
 *                  function call.
 *                  The counting sequence is stopped by LedSet(LED_OFF)
 *
 * @param Function  Select LED funtionality:
 *                  .Count - number of counts (0-255)
 *                  .Invert - true is invert, else false
 *                  .Time[COUNTING_ON]   - counting pulse on time,
 *                  .Time[COUNTING_OFF]  - counting pulse off time
 *                  .Time[COUNTING_PAUSE]- pause between counting sequences, set to 0
 *                                        if only one counting sequence is wanted
 *                  .Time[] is 1/1.024 ms resolution, use MWORK_MSEC().
 ***********************************************************************/
static inline void LedCounting(uint32_t Leds, const struct led_counting_t * Function)
{
  LedSet(Leds, (uint32_t)Function);
}

/** \} */

/** \name Application' LED configuration and supplied functions.
 *  \{
 *  The following is the LED driver setup for application's board.h and
 *  board.c files.
 */

#ifdef LED_DRIVER_DOXYGEN

#define LED_FLASHING_ENABLED        true/false    //!< If true, LED driver supports flashing

#define LED_COUNTING_ENABLED        true/false    //!< If true, LED driver supports sequence flashing

#define NUMBER_OF_FLASHING_PATTERN  Number        //!< Number == How many flashing patterns defined?

const struct led_flash_t LedFlashing[NUMBER_OF_FLASHING_PATTERN]; //!< User's array of \ref led_flash_t defines flashing patterns

/**********************************************************************/
/**
 * \brief User supplied function to update LEDs.
 *
 * The function must be provided to LED driver in board.h and allows application
 * to use for example GPIO expanders instead of processor' GPIO to drive LEDs.
 *
 * LED bit positions are abstract and application can map them to physical GPIO
 * if required. So for example if application requests to turn LED #2 on, then
 * the driver calls this UpdateLeds() callback with bit #2 settled.
 *
 * \param  BitLedOn Bit values (on/off) for all 32 LEDs
 *
 **********************************************************************/
static void UpdateLeds(uint32_t BitLedOn);

#endif

/** \} */

/** \} led */

#endif