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 7793cc2b3c2c68e7064c51becd91fa86caa3836d..cb3c9b3cd93b2325afb750bc87fd03c4942b9ecc 100644 (file)
--- a/rpp/include/rpp/hbr.h
+++ b/rpp/include/rpp/hbr.h
@@ -14,13 +14,93 @@
 
 /**
  * HBR module initialization.
+ *
  * Call this method before using this module.
  *
- * @return SUCCESS if initialization successful.
- *         FAIL is module already initialized.
+ * This function is not thread safe. Do not call it from multiple threads.
+ *
+ * @return SUCCESS if initialization successful.\n
+ *         FAILURE if module already initialized.
  */
-void rpp_hbr_init();
+int8_t rpp_hbr_init();
 
 
-#endif /* __RPP_HBR_H */
+/**
+ * Enable the H-Bridge output and set PWM frequency.
+ *
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
+ *
+ * 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
+ *                      55us (~18kHz, 18181.8181_ Hz to be precise) is used.
+ *
+ * @return SUCCESS if successful.\n
+ *         FAILURE if H-Bridge was already enabled or watchdog task could not
+ *                 be created.
+ *
+ * @note Period considerations from Software perspective (hardware verification
+ * required):
+ * @par
+ *     - Minimum value is [1us]:
+ *         - 50us => 20 kHz
+ *         - System clock is 80MHz.
+ * @par
+ *     - Maximum value is [2147483647us] (full 32bit signed integer):
+ *         - 2147483647us = 2147483.647 ms = 2147.483647 s =
+ *           ~35.791394 min => 0.000465661129 Hz -> 0.0... MHz
+ */
+int8_t rpp_hbr_enable(int32_t period);
+
+
+/**
+ * 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 : 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:
+ *
+ * @code
+ * 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); // 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 output.
+ * @endcode
+ *
+ * @return SUCCESS if change was successful.\n
+ *         -1 if H-Bridge is not enabled. Call rpp_hbr_enable() first.\n
+ *         -2 if cmd is out of range.
+ */
+int8_t rpp_hbr_control(double cmd);
+
+
+/**
+ * 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 already disabled.
+ */
+int8_t rpp_hbr_disable();
+
 
+#endif /* __RPP_HBR_H */