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 for control.
  28  *
  29  * By default, the H-Bridge is initialized with the given period (which implies
  30  * frequency), 0 duty cycle, output disabled and direction HIGH. Once enabled
  31  * with this function, the H-Bridge can be controlled with rpp_hbr_control()
  32  * (see below).
  33  *
  34  * @param[in] period    Period of the PWM in microseconds (us). If period is
  35  *                      less than 1 (the minimum, see note below) the default of
  36  *                      55us (~18kHz, 18181.8181_ Hz to be precise) is used.
  37  *
  38  * @return SUCCESS if successful.\n
  39  *         FAILURE if H-Bridge was already enabled or watchdog task could not
  40  *                 be created.
  41  *
  42  * @note Period considerations from Software perspective (hardware verification
  43  * required):
  44  * @par
  45  *     - Minimum value is [1us]:
  46  *         - 50us => 20 kHz
  47  *         - System clock is 80MHz.
  48  * @par
  49  *     - Maximum value is [2147483647us] (full 32bit signed integer):
  50  *         - 2147483647us = 2147483.647 ms = 2147.483647 s =
  51  *           ~35.791394 min => 0.000465661129 Hz -> 0.0... MHz
  52  */
  53 int8_t rpp_hbr_enable(int32_t period);
  54
  55
  56 /**
  57  * Control the H-Bridge direction, enabled/disabled and PWM.
  58  *
  59  * @param[in] cmd       [-1.0, 1.0] A double between the previous range to
  60  *                      command the H-Bridge in the following manner:
  61  *                          - cmd == 0 : Disable H-Bridge (no PWM or direction).
  62  *                          - cmd  > 0 : H-bridge output enabled, direction set
  63  *                                       to HIGH and PWM duty cycle proportional
  64  *                                       with 1% resolution.
  65  *                          - cmd  < 0 : H-bridge output enabled, direction set
  66  *                                       to LOW  and PWM duty cycle proportional
  67  *                                       with 1% resolution.
  68  *
  69  * Consider the following:
  70  *
  71  * @code
  72  * rpp_hbr_enable(-1);    // Enable H-Bridge at 18kHz.
  73  * rpp_hbr_control( 1.0); // Set direction to HIGH and 100% PWM duty cycle.
  74  * (...)
  75  * rpp_hbr_control( 0.0); // No direction and 0% duty cycle.
  76  * (...)
  77  * rpp_hbr_control(-0.5); // Set direction to LOW  and  50% PWM duty cycle.
  78  * rpp_hbr_disable();     // Disable H-Bridge.
  79  * @endcode
  80  *
  81  * @return SUCCESS if change was successful.\n
  82  *         -1 if H-Bridge is not enabled. Call rpp_hbr_enable() first.\n
  83  *         -2 if cmd is out of range.
  84  */
  85 int8_t rpp_hbr_control(double cmd);
  86
  87
  88 /**
  89  * Disable the H-Bridge.
  90  *
  91  * Completely disable H-Bridge. After this call the H-Bridge cannot be
  92  * controlled again until another call to rpp_hbr_enable() is made.
  93  *
  94  * @return SUCCESS if successful.\n
  95  *         FAILURE if H-Bridge was disabled already.
  96  */
  97 int8_t rpp_hbr_disable();
  98
  99
 100 #endif /* __RPP_HBR_H */
 101