rpp/include/rpp/hbr.h

   1 /**
   2  * H-Bridge Output RPP API header file.
   3  *
   4  * @file hbr.h
   5  *
   6  * @copyright Copyright (C) 2013 Czech Technical University in Prague
   7  *
   8  * @author Carlos Jenkins <carlos@jenkins.co.cr>
   9  */
  10
  11
  12 #ifndef __RPP_HBR_H
  13 #define __RPP_HBR_H
  14
  15 /**
  16  * HBR module initialization.
  17  *
  18  * Call this method before using this module.
  19  *
  20  * @return SUCCESS if initialization successful.\n
  21  *         FAILURE if module already initialized.
  22  */
  23 int8_t rpp_hbr_init();
  24
  25
  26 /**
  27  * Enable the H-Bridge output and set PWM frequency.
  28  *
  29  * Sets duty cycle to zero, direction to LOW and enables the H-Bridge
  30  * output. Duty cycle and direction can be later controlled with
  31  * rpp_hbr_control() (see below).
  32  *
  33  * @param[in] period    Period of the PWM in microseconds (us). If period is
  34  *                      less than 1 (the minimum, see note below) the default of
  35  *                      55us (~18kHz, 18181.8181_ Hz to be precise) is used.
  36  *
  37  * @return SUCCESS if successful.\n
  38  *         FAILURE if H-Bridge was already enabled or watchdog task could not
  39  *                 be created.
  40  *
  41  * @note Period considerations from Software perspective (hardware verification
  42  * required):
  43  * @par
  44  *     - Minimum value is [1us]:
  45  *         - 50us => 20 kHz
  46  *         - System clock is 80MHz.
  47  * @par
  48  *     - Maximum value is [2147483647us] (full 32bit signed integer):
  49  *         - 2147483647us = 2147483.647 ms = 2147.483647 s =
  50  *           ~35.791394 min => 0.000465661129 Hz -> 0.0... MHz
  51  */
  52 int8_t rpp_hbr_enable(int32_t period);
  53
  54
  55 /**
  56  * Control the H-Bridge direction and PWM duty cycle.
  57  *
  58  * @param[in] cmd       [-1.0, 1.0] A double between the previous range to
  59  *                      command the H-Bridge in the following manner:
  60  *                          - cmd > 0 : direction set to HIGH and PWM
  61  *                                       duty cycle proportional with
  62  *                                       1% resolution.
  63  *                          - cmd <= 0 : direction set to LOW and PWM
  64  *                                        duty cycle proportional with
  65  *                                        1% resolution.
  66  *
  67  * Consider the following:
  68  *
  69  * @code
  70  * rpp_hbr_enable(-1);    // Enable H-Bridge at 18kHz.
  71  * rpp_hbr_control( 1.0); // Set direction to HIGH and 100% PWM duty cycle.
  72  * (...)
  73  * rpp_hbr_control( 0.0); // 0% duty cycle, but H-Bridge output active (low-side active free wheeling)
  74  * (...)
  75  * rpp_hbr_control(-0.5); // Set direction to LOW  and  50% PWM duty cycle.
  76  * rpp_hbr_disable();     // Disable H-Bridge output.
  77  * @endcode
  78  *
  79  * @return SUCCESS if change was successful.\n
  80  *         -1 if H-Bridge is not enabled. Call rpp_hbr_enable() first.\n
  81  *         -2 if cmd is out of range.
  82  */
  83 int8_t rpp_hbr_control(double cmd);
  84
  85
  86 /**
  87  * Disable the H-Bridge output.
  88  *
  89  * Completely disable H-Bridge. After this call the H-Bridge cannot be
  90  * controlled again until another call to rpp_hbr_enable() is made.
  91  *
  92  * @return SUCCESS if successful.\n
  93  *         FAILURE if H-Bridge was already disabled.
  94  */
  95 int8_t rpp_hbr_disable();
  96
  97
  98 #endif /* __RPP_HBR_H */