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