Merge pull request #83 from Legion2/documentation

Improve the API Documentation

Author: Legion2

README.md

@@ -126,6 +126,9 @@ Then the third argument of the `scale` function is `144`.
 For both functions it's **important**, that the CRGB arrays have at least the length of the physical LED strip.
 This means if your LED channel from iCUE has 50 LEDs and you use the `repeat` function to control 100 physical LEDs you MUST declare the CRGB array at least with a length of 100.
 
+# License
+This project is licensed under the Apache 2.0 License.
+
 # DISCLAIMERS
 This is a DO IT YOURSELF project, use at your own risk!
 

examples/CommanderPRO/PWMFan.cpp

@@ -23,7 +23,7 @@ PWMFan::PWMFan(uint8_t pwmPin, uint16_t minRPM ,uint16_t maxRPM) : pwmPin(pwmPin
 	case TIMER0B:/* 3 */
 #ifdef DEBUG
 		Serial.println(F("Pin not supported as PWM fan pin"));
-		Serial.println(F("We don't want to mess up arduino time functions"));
+		Serial.println(F("We don't want to mess up Arduino time functions"));
 #endif // DEBUG
 		break;
 	case TIMER3A:/* 5 */

examples/CommanderPRO/PWMFan.h

@@ -19,8 +19,14 @@
 
 class PWMFan {
 public:
-	// minRPM should be the rpm value at 0% power and maxRPM at 100% power
-	// These values are used to map speed to power using linear interpolation
+	/**
+	 * PWM fan which maps speed to power using linear interpolation.
+	 * This fan does not read the real RPM values. The Arduino timer for the given pin will be set to higher speed.
+	 * 
+	 * @param pwmPin the Arduino pwm pin for this fan. Not all PWM pins are supported.
+	 * @param minRPM the speed in RPM at 0% power
+	 * @param maxRPM the speed in RPM at 100% power
+	 */
 	PWMFan(uint8_t pwmPin, uint16_t minRPM, uint16_t maxRPM);
 	virtual void setPower(uint8_t percentage);
 	virtual uint8_t calculatePowerFromSpeed(uint16_t rpm);

examples/CommanderPRO/SimpleFanController.cpp

@@ -45,8 +45,8 @@ bool SimpleFanController::updateFans()
 	long currentUpdateNumber = currentUpdate / updateRate;
 	lastUpdate = currentUpdate;
 	if (lastUpdateNumber < currentUpdateNumber) {
-		if (trigger_save) {
-			trigger_save = false;
+		if (triggerSave) {
+			triggerSave = false;
 			save();
 		}
 
@@ -106,7 +106,7 @@ void SimpleFanController::setFanSpeed(uint8_t fan, uint16_t speed)
 	fanData[fan].speed = speed;
 	fanData[fan].mode = FAN_CONTROL_MODE_FIXED_RPM;
 	fanData[fan].power = fans[fan] != nullptr ? fans[fan]->calculatePowerFromSpeed(speed) : 0;
-	trigger_save = true;
+	triggerSave = true;
 }
 
 uint8_t SimpleFanController::getFanPower(uint8_t fan)
@@ -119,15 +119,15 @@ void SimpleFanController::setFanPower(uint8_t fan, uint8_t percentage)
 	fanData[fan].power = percentage;
 	fanData[fan].mode = FAN_CONTROL_MODE_FIXED_POWER;
 	fanData[fan].speed = fans[fan] != nullptr ? fans[fan]->calculateSpeedFromPower(percentage) : 0;
-	trigger_save = true;
+	triggerSave = true;
 }
 
 void SimpleFanController::setFanCurve(uint8_t fan, uint8_t group, FanCurve& fanCurve)
 {
 	fanData[fan].fanCurve = fanCurve;
 	fanData[fan].tempGroup = group;
 	fanData[fan].mode = FAN_CONTROL_MODE_CURVE;
-	trigger_save = true;
+	triggerSave = true;
 }
 
 void SimpleFanController::setFanExternalTemperature(uint8_t fan, uint16_t temp)
@@ -140,16 +140,16 @@ void SimpleFanController::setFanForce3PinMode(bool flag)
 	force3PinMode = flag;
 }
 
-uint8_t SimpleFanController::getFanDetectionType(uint8_t fan)
+FanDetectionType SimpleFanController::getFanDetectionType(uint8_t fan)
 {
 	return fanData[fan].detectionType;
 }
 
-void SimpleFanController::setFanDetectionType(uint8_t fan, uint8_t type)
+void SimpleFanController::setFanDetectionType(uint8_t fan, FanDetectionType type)
 {
 	if (fanData[fan].detectionType != type) {
 		fanData[fan].detectionType = type;
-		trigger_save = true;
+		triggerSave = true;
 	}
 }
 

examples/CommanderPRO/SimpleFanController.h

@@ -28,19 +28,35 @@ struct FanData {
 	uint8_t mode = FAN_CONTROL_MODE_FIXED_POWER;
 	uint8_t power = 0;
 	uint16_t speed = 0;
-	uint8_t detectionType = FAN_DETECTION_TYPE_DISCONNECTED;
+	FanDetectionType detectionType = FanDetectionType::Disconnected;
 	uint8_t tempGroup;
 	FanCurve fanCurve;
 };
 
-// This simple Fan Controller implementation does not implement all features of a Fan Controller.
-// It should only demonstrate how to implement your own Fan Controller.
+/**
+ * This simple Fan Controller implementation does not implement all features of a Fan Controller.
+ * It should only demonstrate how to implement your own Fan Controller.
+ */
 class SimpleFanController : public FanController {
 public:
-	// Fan Contorller must use the EEPROM else on startup the fans can't be controlled
-	// updateRate it the time between fan speed updates in ms
+	/**
+	 * Fan Controller must use the EEPROM else on startup the fans can't be controlled
+	 * 
+	 * @param temperatureController the TemperatureController used to get the temperature to control the fans
+	 * @param updateRate is the time between fan speed updates in ms
+	 * @param eEPROMAdress the address where the data is stored in EEPROM
+	 */
 	SimpleFanController(TemperatureController* temperatureController, uint16_t updateRate, uint16_t eEPROMAdress);
+	/**
+	 * Add a fan to the Controller.
+	 * 
+	 * @param index the index of the fan
+	 * @param fan the fan object
+	 */
 	void addFan(uint8_t index, PWMFan* fan);
+	/**
+	 * Update the fan speeds based on the temperature and commands.
+	 */
 	virtual bool updateFans();
 protected:
 	virtual uint16_t getFanSpeed(uint8_t fan) override;
@@ -50,8 +66,8 @@ class SimpleFanController : public FanController {
 	virtual void setFanCurve(uint8_t fan, uint8_t group, FanCurve& fanCurve) override;
 	virtual void setFanExternalTemperature(uint8_t fan, uint16_t temp) override;
 	virtual void setFanForce3PinMode(bool flag) override;
-	virtual uint8_t getFanDetectionType(uint8_t fan) override;
-	virtual void setFanDetectionType(uint8_t fan, uint8_t type) override;
+	virtual FanDetectionType getFanDetectionType(uint8_t fan) override;
+	virtual void setFanDetectionType(uint8_t fan, FanDetectionType type) override;
 	bool load();
 	bool save();
 
@@ -62,6 +78,9 @@ class SimpleFanController : public FanController {
 	uint16_t externalTemp[FAN_NUM];
 	uint16_t updateRate;
 	uint16_t eEPROMAdress;
-	bool trigger_save = false;
+	/**
+	 * Indicates that the configuration of the fans has been changed and should be saved.
+	 */
+	bool triggerSave = false;
 	long lastUpdate = 0;
 };

examples/CommanderPRO/ThermistorTemperatureController.h

@@ -16,14 +16,24 @@
 #pragma once
 
 #include "TemperatureController.h"
-/*
-Thermistor Schematic :
-    | ---- [10k - Resistor] ----- | ----- [Thermistor] ---- |
-    |                             |                         |
- [Ground]                     Analog Pin                  [+5v]
-*/
+/**
+ * This TemperatureController uses Thermistors and Resistors to messure the temperature. It does not implement the voltage rail measurements.
+ *
+ * Thermistor Schematic:
+ * <pre>
+ *     | ---- [10k - Resistor] ---- | ---- [Thermistor] ---- |
+ *     |                            |                        |
+ *  [Ground]                    Analog Pin                 [+5v]
+ * </pre>
+ */
 class ThermistorTemperatureController : public TemperatureController {
 public:
+	/**
+	 * Add a Sensor to the TemperatureController using an Arduino analog pin connected as shown in {@link ThermistorTemperatureController}.
+	 *
+	 * @param index the index of the sensorPins
+	 * @param pin the Arduino analog pin
+	 */
 	void addSensor(uint8_t index, uint8_t pin);
 protected:
 	virtual uint16_t getTemperatureValue(uint8_t temperatureSensor) override;

examples/SingleStripLightingNodePRO/SingleStripLightingNodePRO.ino

@@ -19,7 +19,7 @@
 // The number of LEDs per channel.
 #define CHANNEL_LED_COUNT 50
 
-// Total count of LEDs on all channels, the value is calculated based on the leds per channel.
+// Total count of LEDs on all channels, the value is calculated based on the LEDs per channel.
 #define NUM_LEDS (CHANNEL_LED_COUNT * 2)
 
 // The Arduino pin where the physical LEDs are connected.

src/CLPUtils.h

@@ -58,7 +58,7 @@ namespace CLP
 	bool isResetID(const uint8_t* deviceId);
 
 	/**
-	 * This will disable the RX and TX built in leds on Arduino Leonardo, Micro and Pro Micro.
+	 * This will disable the RX and TX built in LEDs on Arduino Leonardo, Micro and Pro Micro.
 	 */
 	void disableBuildInLEDs();
 

src/CorsairLightingNodePRO.h

@@ -18,7 +18,7 @@
 #include "Arduino.h"
 #include "CorsairLightingFirmware.h" 
 #include "FastLEDController.h"
-#include "CorsairLightingProtocol.h"
+#include "CorsairLightingProtocolController.h"
 #include "CorsairLightingProtocolHID.h"
 #include <FastLED.h>
 

src/CorsairLightingProtocol.h

@@ -15,7 +15,10 @@
 */
 #pragma once
 
-// central include file for CorsairLightingProtocolController
+/**
+ * @file
+ * The central include file for CorsairLightingProtocol.
+ */
 #include "CorsairLightingFirmware.h"
 #include "CorsairLightingNodePRO.h"
 #include "CorsairLightingProtocolConstants.h"

src/CorsairLightingProtocolController.h

@@ -32,25 +32,25 @@ class CorsairLightingProtocolController
 {
 public:
 	/**
-	 * The constructor used to create a Lighting Node PRO.
-	 * 
+	 * The constructor used to create a Lighting only device.
+	 *
 	 * @param l The LEDController which should be used to control the LEDs of the created Lighting Node PRO
 	 * @param c The CorsairLightingFirmware used to handle Firmware related commands
 	 */
 	CorsairLightingProtocolController(ILEDController* l, CorsairLightingFirmware* c);
 	/**
-	 * The constructor used to create a Commander PRO.
-	 * 
+	 * The constructor used to create a device with lighting, temperature and fan controller functionality (Commander PRO).
+	 *
 	 * @param l The LEDController which should be used to control the LEDs of the created Commander PRO
 	 * @param t The TemperatureController which used to messure the temperature of the created Commander PRO
 	 * @param f The FanController used to control the fans of the created Commander PRO
 	 * @param c The CorsairLightingFirmware used to handle Firmware related commands
 	 */
 	CorsairLightingProtocolController(ILEDController* l, ITemperatureController* t, IFanController* f, CorsairLightingFirmware* c);
 	/**
-	 * The only public function of the CorsairLightingProtocolController. It must be called to process a command with was received from iCUE. This
-	 * function is normaly called by CorsairLightingProtocolHID and CorsairLightingProtocolSerial adapters.
-	 * 
+	 * The only public function of the CorsairLightingProtocolController. It must be called to process a command which was received from iCUE.
+	 * This function is normally called by CorsairLightingProtocolHID and CorsairLightingProtocolSerial adapters.
+	 *
 	 * @param command The command received from iCUE
 	 * @param response The response callback which can be called to response to the command
 	 */

src/CorsairLightingProtocolHID.cpp

@@ -27,12 +27,12 @@ bool printCommand = PRINT_COMMAND;
 bool printResponse = PRINT_RESPONSE;
 #endif
 
-CorsairLightingProtocolHID::CorsairLightingProtocolHID(CorsairLightingProtocolController* cLP) : cLP(cLP)
+CorsairLightingProtocolHID::CorsairLightingProtocolHID(CorsairLightingProtocolController* controller) : controller(controller)
 {
 	RawHID.begin(rawhidData, sizeof(rawhidData));
 }
 
-CorsairLightingProtocolHID::CorsairLightingProtocolHID(CorsairLightingProtocolController* cLP, const char* serialNumber) : CorsairLightingProtocolHID(cLP)
+CorsairLightingProtocolHID::CorsairLightingProtocolHID(CorsairLightingProtocolController* controller, const char* serialNumber) : CorsairLightingProtocolHID(controller)
 {
 	RawHID.setSerialNumber(serialNumber);
 }
@@ -43,7 +43,7 @@ void CorsairLightingProtocolHID::update()
 	{
 		Command command;
 		getCommand(command);
-		cLP->handleCommand(command, this);
+		controller->handleCommand(command, this);
 	}
 }
 

src/CorsairLightingProtocolHID.h

@@ -28,14 +28,34 @@ extern bool printCommand;
 extern bool printResponse;
 #endif
 
+/**
+ * The HID Adapter for CorsairLightingProtocolController. This adapter uses the USB HID interface
+ * directly to mimic a corsair device. This adapter can only be used when the USB interface is
+ * accessable by the sketch.
+ */
 class CorsairLightingProtocolHID : CorsairLightingProtocolResponse {
 public:
-	CorsairLightingProtocolHID(CorsairLightingProtocolController* cLP);
-	CorsairLightingProtocolHID(CorsairLightingProtocolController* cLP, const char* serialNumber);
+	/**
+	 * Create a new adapter for CorsairLightingProtocolController using the default Serial Number.
+	 *
+	 * @param controller the CorsairLightingProtocolController
+	 */
+	CorsairLightingProtocolHID(CorsairLightingProtocolController* controller);
+	/**
+	 * Create a new adapter for using the given Serial Number for the usb interface.
+	 *
+	 * @param controller the CorsairLightingProtocolController
+	 * @param serialNumber the Serial Number used for the USB interface
+	 */
+	CorsairLightingProtocolHID(CorsairLightingProtocolController* controller, const char* serialNumber);
+	/**
+	* Read commands form HID interface and pass them to the contoller.
+	* This function must be called in loop.
+	*/
 	void update();
 protected:
 	uint8_t rawhidData[COMMAND_SIZE];
-	CorsairLightingProtocolController* const cLP;
+	CorsairLightingProtocolController* const controller;
 
 	bool available() const;
 	void getCommand(Command& command);

src/CorsairLightingProtocolResponse.h

@@ -19,9 +19,29 @@
 
 class CorsairLightingProtocolResponse {
 public:
+	/**
+	 * Send 64 bytes via the CorsairLightingProtocol. All unset bytes will be filled with zeros.
+	 *
+	 * @param data the array with the data
+	 * @param size the length of the array
+	 */
 	virtual void send(const uint8_t* data, size_t size) const;
+	/**
+	 * Send an error.
+	 */
 	virtual void sendError() const;
+	/**
+	 * Send data from program memory.
+	 *
+	 * @param data the array with the data, the pointer must point to program memory
+	 * @param size the length of the array which should be send.
+	 */
 	virtual void send_P(const uint8_t* data, size_t size) const;
-	// Send x byte data via the CorsairLightingProtocol.
+	/**
+	 * Send some bytes data via the CorsairLightingProtocol.
+	 *
+	 * @param data the array with the data
+	 * @param x the length of the array which should be send.
+	 */
 	virtual void sendX(const uint8_t* data, const size_t x) const = 0;
 };

src/CorsairLightingProtocolSerial.cpp

@@ -15,7 +15,7 @@
 */
 #include "CorsairLightingProtocolSerial.h"
 
-CorsairLightingProtocolSerial::CorsairLightingProtocolSerial(CorsairLightingProtocolController* cLP) : cLP(cLP) {}
+CorsairLightingProtocolSerial::CorsairLightingProtocolSerial(CorsairLightingProtocolController* controller) : controller(controller) {}
 
 void CorsairLightingProtocolSerial::setup()
 {
@@ -30,7 +30,7 @@ void CorsairLightingProtocolSerial::update()
 	{
 		Command command;
 		memcpy(command.raw, rawCommand, sizeof(command.raw));
-		cLP->handleCommand(command, this);
+		controller->handleCommand(command, this);
 	}
 }