✨ Add Optical Get/Set Integration Time (#719)

* Added optical set/get integration time

* bump version number

---------
Co-authored-by: Grace Lu <[email protected]>

include/api.h

@@ -41,9 +41,8 @@
 
 #define PROS_VERSION_MAJOR 4
 #define PROS_VERSION_MINOR 1
-
-#define PROS_VERSION_PATCH 0
-#define PROS_VERSION_STRING "4.1.0"
+#define PROS_VERSION_PATCH 1
+#define PROS_VERSION_STRING "4.1.1"
 
 
 #include "pros/adi.h"

include/pros/optical.h

@@ -460,6 +460,39 @@ int32_t optical_enable_gesture(uint8_t port);
  */
 int32_t optical_disable_gesture(uint8_t port);
 
+/**
+ * Get integration time (update rate) of the optical sensor in milliseconds, with
+ * minimum time being 
+ *
+ * This function uses the following values of errno when an error state is
+ * reached:
+ * ENXIO - The given value is not within the range of V5 ports (1-21).
+ * ENODEV - The port cannot be configured as an Optical Sensor
+ *
+ * \param port
+ *        The V5 Optical Sensor port number from 1-21
+ * \return Integration time in milliseconds if the operation is successful 
+ * or PROS_ERR if the operation failed, setting errno.
+ */
+double optical_get_integration_time(uint8_t port);
+
+/**
+ * Set integration time (update rate) of the optical sensor in milliseconds.
+ *
+ * This function uses the following values of errno when an error state is
+ * reached:
+ * ENXIO - The given value is not within the range of V5 ports (1-21).
+ * ENODEV - The port cannot be configured as an Optical Sensor
+ *
+ * \param port
+ *        The V5 Optical Sensor port number from 1-21
+ * \param time
+ *        The desired integration time in milliseconds
+ * \return 1 if the operation is successful or PROS_ERR if the operation failed,
+ * setting errno.
+ */
+int32_t optical_set_integration_time(uint8_t port, double time);
+
 ///@}
 
 ///@}

include/pros/optical.hpp

@@ -398,6 +398,36 @@ class Optical : public Device {
 	 */
 	virtual std::int32_t disable_gesture();
 
+	/**
+	 * Set integration time (update rate) of the optical sensor in milliseconds, with
+	 * minimum time being 3 ms and maximum time being 712 ms. Default is 100 ms, with the 
+	 * optical sensor communciating with the V5 brain every 20 ms. 
+	 *
+	 * This function uses the following values of errno when an error state is
+	 * reached:
+	 * ENXIO - The given value is not within the range of V5 ports (1-21).
+	 * ENODEV - The port cannot be configured as an Optical Sensor
+ 	 *
+	 * \return 1 if the operation is successful or PROS_ERR_F if the operation failed,
+	 * setting errno.
+	 */
+	double get_integration_time();
+
+	/**
+	 * Get integration time (update rate) of the optical sensor in milliseconds.
+	 *
+	 * This function uses the following values of errno when an error state is
+	 * reached:
+	 * ENXIO - The given value is not within the range of V5 ports (1-21).
+	 * ENODEV - The port cannot be configured as an Optical Sensor
+	 *
+	 * \param time
+	 *        The desired integration time in milliseconds
+	 * \return Integration time in milliseconds if the operation is successful 
+	 *  or PROS_ERR if the operation failed, setting errno.
+	 */
+	std::int32_t set_integration_time(double time);
+
 	/**
 	 * This is the overload for the << operator for printing to streams
 	 *

src/devices/vdml_optical.c

@@ -17,6 +17,11 @@
 #include "vdml/registry.h"
 #include "vdml/vdml.h"
 
+// Source for these figures: 
+// https://www.vexforum.com/t/v5-optical-sensor-refresh-rate/109632/9
+#define MIN_INTEGRATION_TIME 3 // ms
+#define MAX_INTEGRATION_TIME 712 // ms
+
 double optical_get_hue(uint8_t port) {
 	claim_port_i(port - 1, E_DEVICE_OPTICAL);
 	double rtn = vexDeviceOpticalHueGet(device->device_info);
@@ -134,3 +139,20 @@ int32_t optical_disable_gesture(uint8_t port) {
 	vexDeviceOpticalGestureDisable(device->device_info);
 	return_port(port - 1, PROS_SUCCESS);
 }
+
+double optical_get_integration_time(uint8_t port) {
+	claim_port_f(port - 1, E_DEVICE_OPTICAL);
+	double rtv = vexDeviceOpticalIntegrationTimeGet(device->device_info);
+	return_port(port - 1, rtv);
+}
+
+int32_t optical_set_integration_time(uint8_t port, double time) {
+	claim_port_i(port - 1, E_DEVICE_OPTICAL);
+	// going to set the time to minimum of 3 ms, 3 ms is possible but impractical.
+	time = time < MIN_INTEGRATION_TIME ? MIN_INTEGRATION_TIME : time;
+	// also boundary limit max integration time too
+	time = time > MAX_INTEGRATION_TIME ? MAX_INTEGRATION_TIME : time;
+
+	vexDeviceOpticalIntegrationTimeSet(device->device_info, time);
+	return_port(port - 1, PROS_SUCCESS);
+}

src/devices/vdml_optical.cpp

@@ -10,6 +10,7 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  */
 
+#include "pros/optical.h"
 #include "pros/optical.hpp"
 #include "vdml/vdml.h"
 
@@ -76,6 +77,13 @@ std::int32_t Optical::disable_gesture(){
   return optical_disable_gesture(_port);
 }
 
+double Optical::get_integration_time() {
+  return optical_get_integration_time(_port);
+}
+
+std::int32_t Optical::set_integration_time(double time) {
+  return optical_set_integration_time(_port, time);
+}
 
 std::ostream& operator<<(std::ostream& os, pros::Optical& optical) {
   pros::c::optical_rgb_s_t rgb = optical.get_rgb(); 

version

@@ -1 +1 @@
-4.1.0
+4.1.1