Make the RPP layer thread safe

[pes-rpp/rpp-lib.git] / rpp / include / rpp / hbr.h

diff --git a/rpp/include/rpp/hbr.h b/rpp/include/rpp/hbr.h
index 8d9d9973ca937d474ac45f214455507fddcd3a1d..cb3c9b3cd93b2325afb750bc87fd03c4942b9ecc 100644 (file)
--- a/rpp/include/rpp/hbr.h
+++ b/rpp/include/rpp/hbr.h
@@ -17,6 +17,8 @@
  *
  * Call this method before using this module.
  *
+ * This function is not thread safe. Do not call it from multiple threads.
+ *
  * @return SUCCESS if initialization successful.\n
  *         FAILURE if module already initialized.
  */
@@ -24,12 +26,13 @@ int8_t rpp_hbr_init();
 
 
 /**
- * Enable the H-Bridge for control.
+ * Enable the H-Bridge output and set PWM frequency.
+ *
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
  *
- * By default, the H-Bridge is initialized with the given period (which implies
- * frequency), 0 duty cycle, output disabled and direction HIGH. Once enabled
- * with this function, the H-Bridge can be controlled with rpp_hbr_control()
- * (see below).
+ * Sets duty cycle to zero, direction to LOW and enables the H-Bridge
+ * output. Duty cycle and direction can be later controlled with
+ * rpp_hbr_control() (see below).
  *
  * @param[in] period    Period of the PWM in microseconds (us). If period is
  *                      less than 1 (the minimum, see note below) the default of
@@ -54,17 +57,18 @@ int8_t rpp_hbr_enable(int32_t period);
 
 
 /**
- * Control the H-Bridge direction, enabled/disabled and PWM.
+ * Control the H-Bridge direction and PWM duty cycle.
+ *
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
  *
  * @param[in] cmd       [-1.0, 1.0] A double between the previous range to
  *                      command the H-Bridge in the following manner:
- *                          - cmd == 0 : Disable H-Bridge (no PWM or direction).
- *                          - cmd  > 0 : H-bridge output enabled, direction set
- *                                       to HIGH and PWM duty cycle proportional
- *                                       with 1% resolution.
- *                          - cmd  < 0 : H-bridge output enabled, direction set
- *                                       to LOW  and PWM duty cycle proportional
- *                                       with 1% resolution.
+ *                          - cmd > 0 : direction set to HIGH and PWM
+ *                                       duty cycle proportional with
+ *                                       1% resolution.
+ *                          - cmd <= 0 : direction set to LOW and PWM
+ *                                        duty cycle proportional with
+ *                                        1% resolution.
  *
  * Consider the following:
  *
@@ -72,10 +76,10 @@ int8_t rpp_hbr_enable(int32_t period);
  * rpp_hbr_enable(-1);    // Enable H-Bridge at 18kHz.
  * rpp_hbr_control( 1.0); // Set direction to HIGH and 100% PWM duty cycle.
  * (...)
- * rpp_hbr_control( 0.0); // No direction and 0% duty cycle.
+ * rpp_hbr_control( 0.0); // 0% duty cycle, but H-Bridge output active (low-side active free wheeling)
  * (...)
  * rpp_hbr_control(-0.5); // Set direction to LOW  and  50% PWM duty cycle.
- * rpp_hbr_disable();     // Disable H-Bridge.
+ * rpp_hbr_disable();     // Disable H-Bridge output.
  * @endcode
  *
  * @return SUCCESS if change was successful.\n
@@ -86,16 +90,17 @@ int8_t rpp_hbr_control(double cmd);
 
 
 /**
- * Disable the H-Bridge.
+ * Disable the H-Bridge output.
+ *
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
  *
  * Completely disable H-Bridge. After this call the H-Bridge cannot be
  * controlled again until another call to rpp_hbr_enable() is made.
  *
  * @return SUCCESS if successful.\n
- *         FAILURE if H-Bridge was disabled already.
+ *         FAILURE if H-Bridge was already disabled.
  */
 int8_t rpp_hbr_disable();
 
 
 #endif /* __RPP_HBR_H */
-