rpp/lib/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  *         - 1us = 0.001 ms =>
  47  *         - 1000000 Hz = 1 MHz
  48  *         - A pulse of 1% of the duty cycle -> 100 MHz (X)
  49  *         - System clock is 80MHz.
  50  * @par
  51  *     - Maximum value is [2147483647us] (full 32bit signed integer):
  52  *         - 2147483647us = 2147483.647 ms = 2147.483647 s =
  53  *           ~35.791394 min => 0.000465661129 Hz -> 0.0... MHz
  54  */
  55 int8_t rpp_hbr_enable(int32_t period);
  56
  57
  58 /**
  59  * Control the H-Bridge direction, enabled/disabled and PWM.
  60  *
  61  * @param[in] cmd       [-1.0, 1.0] A double between the previous range to
  62  *                      command the H-Bridge in the following manner:
  63  *                          - cmd == 0 : Disable H-Bridge (no PWM or direction).
  64  *                          - cmd  > 0 : H-bridge output enabled, direction set
  65  *                                       to HIGH and PWM duty cycle proportional
  66  *                                       with 1% resolution.
  67  *                          - cmd  < 0 : H-bridge output enabled, direction set
  68  *                                       to LOW  and PWM duty cycle proportional
  69  *                                       with 1% resolution.
  70  *
  71  * Consider the following:
  72  *
  73  * @code
  74  * rpp_hbr_enable(-1);    // Enable H-Bridge at 18kHz.
  75  * rpp_hbr_control( 1.0); // Set direction to HIGH and 100% PWM duty cycle.
  76  * (...)
  77  * rpp_hbr_control( 0.0); // No direction and 0% duty cycle.
  78  * (...)
  79  * rpp_hbr_control(-0.5); // Set direction to LOW  and  50% PWM duty cycle.
  80  * rpp_hbr_disable();     // Disable H-Bridge.
  81  * @endcode
  82  *
  83  * @return SUCCESS if change was successful.\n
  84  *         -1 if H-Bridge is not enabled. Call rpp_hbr_enable() first.\n
  85  *         -2 if cmd is out of range.
  86  */
  87 int8_t rpp_hbr_control(double cmd);
  88
  89
  90 /**
  91  * Disable the H-Bridge.
  92  *
  93  * Completely disable H-Bridge. After this call the H-Bridge cannot be
  94  * controlled again until another call to rpp_hbr_enable() is made.
  95  *
  96  * @return SUCCESS if successful.\n
  97  *         FAILURE if H-Bridge was disabled already.
  98  */
  99 int8_t rpp_hbr_disable();
 100
 101
 102 #endif /* __RPP_HBR_H */
 103