Merge pull request #77 from Legion2/dev

Version 0.8.0

.github/workflows/documentation.yml

@@ -0,0 +1,24 @@
+name: Create Documentation
+
+on: 
+  push:
+    branches:
+    - dev
+
+jobs:
+  doxygen:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Install doxygen
+      run: sudo apt install doxygen graphviz
+    - name: Run doxygen
+      run: doxygen extra/doxygen.conf
+    - name: Deploy to gh-pages
+      uses: peaceiris/[email protected]
+      env:
+        ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
+        PUBLISH_BRANCH: gh-pages
+        PUBLISH_DIR: doxygen/html

.github/workflows/push.yml

@@ -6,7 +6,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        sketch: [LightingNodePRO, SingleStripLightingNodePRO, CommanderPRO, DeviceIDTool, RepeatAndScale, TransformLLFansFormatToStrip]
+        sketch: [LightingNodePRO, SingleStripLightingNodePRO, CommanderPRO, DeviceIDTool, RepeatAndScale, TransformLLFansFormatToStrip, LS100]
         board: ["arduino:avr:leonardo", "arduino:avr:micro", "SparkFun:avr:promicro:cpu=16MHzatmega32U4"]
     steps:
     - uses: actions/checkout@master

.gitignore

@@ -267,3 +267,5 @@ __vm/
 *.vcxproj
 *.vcxproj.filters
 *.vcxitems
+
+/doxygen

README.md

@@ -1,4 +1,3 @@
-
 [![arduino-library-badge](https://www.ardu-badge.com/badge/Corsair%20Lighting%20Protocol.svg?)](https://www.ardu-badge.com/Corsair%20Lighting%20Protocol)
 ![Test Status](https://github.com/Legion2/CorsairLightingProtocol/workflows/Test/badge.svg)
 
@@ -13,14 +12,20 @@
 * Use multiple devices at the same time.
 * Repeat or scale LED channels to arbitrary size.
 
-![Overview](docs/Overview.png)
+### Supported Devices
+* Lighting Node PRO
+* Commander PRO
+* Lighting Node CORE
+* LS100 Smart Lighting Controller
+
+![Overview](extra/images/overview.png)
 
 # Getting started
 
 - [Requirements](#requirements)
 - [Install the library](#install-the-library)
 - [Create a Lighting Node PRO](#create-a-lighting-node-pro)
-- [Use the library](#use-the-library)
+- [Use the Lighting Node PRO](#use-the-lighting-node-pro)
 
 ## Requirements
 The library is compatible with all boards using the MCU ATmega32U4.
@@ -29,44 +34,44 @@ It also supports the Arduino Uno and Arduino Mega, **but** this requires the [Ho
 It is **not** compatible with Arduino Nano.
 In the rest of the documentation "Arduino" is used as a synonym for all supported boards regardless of the manufacturer.
 
-As an IDE [Visual Studio](https://visualstudio.microsoft.com/downloads/) with the extension [Visual Micro](https://marketplace.visualstudio.com/items?itemName=VisualMicro.ArduinoIDEforVisualStudio) is recommended.
-Visual Micro provides the required functionality for free, but sometimes ask you to buy the full version.
-Using the Arduino IDE is difficult, but you can find a tutorial in the [wiki](https://github.com/Legion2/CorsairLightingProtocol/wiki/How-to-use-Arduino-IDE).
-
 You have problems with a board not listed here, please open an [Issue](https://github.com/Legion2/CorsairLightingProtocol/issues).
 
 ## Install the library
-Use the [Library-Manager](https://www.visualmicro.com/page/User-Guide.aspx?doc=Library-Manager.html#) to install this library or download a [release](https://github.com/Legion2/CorsairLightingProtocol/releases).
+Use the [Library-Manager](https://www.ardu-badge.com/Corsair%20Lighting%20Protocol/ide) to install this library (Corsair Lighting Protocol).
 Additionally, the [FastLED](http://fastled.io/) library must be installed.
 
 ## Create a Lighting Node PRO
-Open the example "LightingNodePRO", you can find it in the Visual Micro Explorer or the [examples directory](examples).
-The library [FastLED](http://fastled.io/) is used to control the LEDs. For more information on [how to wire the leds](https://github.com/FastLED/FastLED/wiki/Wiring-leds) and [how to set up the LEDs in the code](https://github.com/FastLED/FastLED/wiki/Basic-usage#setting-up-the-leds) see the links.
-After you have done the wiring or at least know which pin is the data pin, you can set this pin in the example sketch and upload it to the Arduino.
-In Visual Studio use the "Release" [configuration](https://github.com/MicrosoftDocs/visualstudio-docs/blob/master/docs/debugger/how-to-set-debug-and-release-configurations.md#change-the-build-configuration).
+This guide will teach you how to create a Lighting Node PRO with an Arduino Leonardo compatible board.
+If you have an Arduino Uno or Mega, see the [other guide](https://github.com/Legion2/CorsairLightingProtocol/wiki/How-to-use-on-Arduino-Uno-and-Arduino-Mega).
+
+1. Open the example "LightingNodePRO", you can find it in Arduino IDE in the File menu->Examples->Corsair Lighting Protocol->LightingNodePRO or in the [examples directory](examples) if you download this project.
+
+   ![open example sketch](extra/images/open-example.png)
+1. Follow [these steps](https://github.com/Legion2/CorsairLightingProtocolBoards#how-to-use-these-boards-in-arduino) to install the CLP Boards and upload the sketch to your Arduino.
+1. Do the wiring.
+   For more information on [how to wire the leds](https://github.com/FastLED/FastLED/wiki/Wiring-leds) and [how to set up the LEDs in the code](https://github.com/FastLED/FastLED/wiki/Basic-usage#setting-up-the-leds) see the links.
+
+   ![the wiring](extra/images/board-wiring.jpg)
+1. Verify that your device works as expected.
+   Open the Windows settings->devices->Other devices.
+   Somewhere in the list of devices, there should be a device called "Lighting Node PRO".
+1. Now open [iCUE](https://www.corsair.com/icue) there should be the "Lighting Node PRO".
 
-To verify that the library works as expected, open the Windows settings -> devices -> connected devices. Somewhere in the list of devices, there should be a device called "Lighting Node PRO". (If not, please open an [Issue](https://github.com/Legion2/CorsairLightingProtocol/issues))
-Open [iCUE](https://www.corsair.com/icue) there should also be the "Lighting Node PRO".
+## Use the Lighting Node PRO
 
-![iCUE RGB Strip example](docs/iCUE.jpg)
+![iCUE RGB Strip example](extra/images/iCUE.jpg)
 
 In iCUE open the "Lighting Setup" tab of the Lighting Node PRO(LNP) and set for both Lighting Channels the device to "RGB Light Strip" and the amount to a tenth of the LEDs you have.
 iCUE groups the LEDs into groups of ten.
 So if you have 20 LEDs, set the amount to 2.
 Now you can create lighting effects in the "Lighting Channel #" tabs.
 
-The example "SingleStripLightingNodePRO" only requires one LED strip connected to the Arduino.
-Because the "SingleStripLightingNodePRO" concatenate the two channels, a total of 120 LEDs can be controlled on a single LED Strip.
-
-## Use the library
-If you want to use this library in your own sketch don't forget to use Visual Studio as IDE and include the [board.txt](examples/LightingNodePRO/board.txt) in the root directory of your sketch.
-
 # Misc
 
+- [API Documentation](https://legion2.github.io/CorsairLightingProtocol/)
 - [How it works](#how-it-works)
 - [Use multiple Devices](#use-multiple-devices)
 - [Repeat or scale LED channel](#repeat-or-scale-led-channel)
-- [Debugging](#debugging)
 
 ## How it works
 This library uses the USB HID interface of the Arduino Micro or Leonardo.
@@ -75,26 +80,41 @@ After uploading a sketch with the library and these IDs, iCUE recognizes the Ard
 In iCUE you can then select the "Lighting Node PRO" and set some lighting effects.
 iCUE sends these via the CorsairLightingProtocol to the Arduino.
 These commands are understood by the library and converted into lighting effects on the RGB strips connected to the Arduino.
+The [FastLED](http://fastled.io/) library is used to control the LEDs.
 
 ## Use multiple Devices
 Each device has two unique IDs, that is, they should be unique.
 You must give each device a unique ID.
-There are two IDs that must be changed `SERIAL_NUMBER` and `DeviceID`.
-
-The `SERIAL_NUMBER` can be changed in the board.txt file.
-Uncomment the line with `SERIAL_NUMBER` and change some characters at the end, don't change the length and only use HEX characters(0-9 and A-F).
-The `DeviceID` can be changed with the [tool](examples/DeviceIDTool/DeviceIDTool.ino)
+There are two IDs that must be changed `Serial Number` and `DeviceID`.
+
+The Serial Number can be set in the constructor of `CorsairLightingProtocolHID` and `CLPUSBSerialBridge` as shown in the [example](examples/AdditionalFeatures/AdditionalFeatures.ino).
+```C++
+const char mySerialNumber[] PROGMEM = "202B6949A967";
+CorsairLightingProtocolHID cHID(&cLP, mySerialNumber);
+```
+The Serial Number MAY only consist of HEX characters (0-9 and A-F).
+
+The DeviceID can be set with the `setDeviceID` function of `CorsairLightingFirmware`.
+```C++
+void setup() {
+    byte deviceId[4] = { 0x9A, 0xDA, 0xA7, 0x8E };
+    firmware.setDeviceID(deviceId);
+    ...
+}
+```
+
+### Alternative
+The `DeviceID` can be changed with the [DeviceIDTool](examples/DeviceIDTool/DeviceIDTool.ino).
 Upload the DeviceIDTool sketch and then open the Serial monitor with baudrate 115200.
 The tool displays the current DeviceID, you can type in a new DeviceID that is saved on the Arduino.
 After that, you can upload another sketch.
 
 ## Repeat or scale LED channel
 You can repeat or scale LED channel controlled by iCUE onto physical LED strips.
-This is very useful if you have very long LED strips that are longer than 60/96 LEDs.
+This is very useful if you have very long LED strips that are longer than 60/96/135 LEDs.
 This is the maximum number iCUE supports.
 
 To repeat or scale a LED channel you must apply the `CLP::repeat` or the `CLP:scale` function in the update hook of the FastLEDController.
-The functions must be included from `FastLEDControllerUtils.h`.
 See the [RepeatAndScale](examples/RepeatAndScale/RepeatAndScale.ino) example for the complete code.
 Both functions take the FastLEDController pointer and the channel index as arguments.
 Additionally, the `repeat` function takes as an argument how often the LED channel should be repeated.
@@ -106,16 +126,6 @@ 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.
 
-## Debugging
-For debugging don't use the integrated debugger of Visual Studio, as it will most likely break the USB communication.
-Use the `DEBUG` macro and the Serial Monitor.
-With the `-DDEBUG` flag you can enable debugging in the whole project.
-Add this flag in the board.txt file to the `build.extra_flags`.
-
-For advanced debugging you can use the [DebugSketch](examples/DebugSketch/DebugSketch.ino).
-In the board.txt file, the default values for the debugging options can be set.
-After uploading the sketch open the serial monitor with baud rate 115200 and set the line ending to "Line Feed"/"Newline" (`\n`).
-
 # DISCLAIMERS
 This is a DO IT YOURSELF project, use at your own risk!
 
@@ -126,4 +136,5 @@ This is a DO IT YOURSELF project, use at your own risk!
 
 ## Related projects
 - [CorsairArduinoController](https://github.com/TylerSeiford/CorsairArduinoController)
+- [CorsairLightingProtocolBoards](https://github.com/Legion2/CorsairLightingProtocolBoards)
 - [OpenCorsairLighting](https://github.com/McHauge/OpenCorsairLighting)

examples/AdditionalFeatures/AdditionalFeatures.ino

@@ -0,0 +1,50 @@
+/*
+   Copyright 2019 Leon Kiefer
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+	   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+#include <CorsairLightingProtocol.h>
+#include <FastLED.h>
+
+#define DATA_PIN_CHANNEL_1 2
+#define DATA_PIN_CHANNEL_2 3
+
+CRGB ledsChannel1[60];
+CRGB ledsChannel2[60];
+
+const char mySerialNumber[] PROGMEM = "202B6949A967";
+
+CorsairLightingFirmware firmware = corsairLightingNodePROFirmware();
+FastLEDController ledController(true);
+CorsairLightingProtocolController cLP(&ledController, &firmware);
+CorsairLightingProtocolHID cHID(&cLP, mySerialNumber);
+
+void setup() {
+	CLP::disableBuildInLEDs();
+	if (CLP::shouldReset(&firmware)) {
+		CLP::reset(&firmware);
+		ledController.reset();
+	}
+	FastLED.addLeds<NEOPIXEL, DATA_PIN_CHANNEL_1>(ledsChannel1, 60);
+	FastLED.addLeds<NEOPIXEL, DATA_PIN_CHANNEL_2>(ledsChannel2, 60);
+	ledController.addLEDs(0, ledsChannel1, 60);
+	ledController.addLEDs(1, ledsChannel2, 60);
+}
+
+void loop() {
+	cHID.update();
+
+	if (ledController.updateLEDs()) {
+		FastLED.show();
+	}
+}

examples/AdditionalFeatures/board.txt

@@ -0,0 +1,6 @@
+# CorsairLightingProtocol build property overrides
+
+build.vid=0x1b1c
+build.pid=0x0c0b
+build.usb_product="Lighting Node PRO"
+build.usb_manufacturer="Corsair"

examples/CommanderPRO/board.txt

@@ -1,11 +1,6 @@
 # build properties for Commander PRO
-#
-
-##############################################################
 
 build.vid=0x1b1c
 build.pid=0x0c10
 build.usb_product="Commander PRO"
 build.usb_manufacturer="Corsair"
-
-#build.extra_flags={build.usb_flags} '-DSERIAL_NUMBER="FB66DF55421900F5"'

examples/DebugSketch/DebugSketch.ino

@@ -15,7 +15,6 @@
 */
 #include <CorsairLightingProtocol.h>
 #include <FastLED.h>
-#include <EEPROM.h>
 
 #define CHANNEL_LED_COUNT 96
 
@@ -60,9 +59,9 @@ void loop() {
 
 void processCommand(String& cmd) {
 	if (cmd == F("print DeviceID")) {
-		byte DeviceId[4];
-		EEPROM.get(EEPROM_ADDRESS_DEVICE_ID, DeviceId);
-		CLP::printDeviceID(DeviceId);
+		byte deviceId[4];
+		firmware.getDeviceID(deviceId);
+		CLP::printDeviceID(deviceId);
 		Serial.println();
 	}
 #ifdef VERBOSE

examples/DebugSketch/board.txt

@@ -1,11 +1,8 @@
 # CorsairLightingProtocol build property overrides
-#
-
-##############################################################
 
 build.vid=0x1b1c
 build.pid=0x0c0b
 build.usb_product="Lighting Node PRO"
 build.usb_manufacturer="Corsair"
 
-build.extra_flags={build.usb_flags} '-DSERIAL_NUMBER="FB66DF55421900F5"' -DDEBUG -DVERBOSE -DPRINT_COMMAND=true -DPRINT_RESPONSE=true -DPRINT_LOOP=true -DPRINT_UPDATE=true
+build.extra_flags={build.usb_flags} -DDEBUG -DVERBOSE -DPRINT_COMMAND=true -DPRINT_RESPONSE=true -DPRINT_LOOP=true -DPRINT_UPDATE=true

examples/DeviceIDTool/DeviceIDTool.ino

@@ -21,10 +21,6 @@
 
 #define EEPROM_ADDRESS_DEVICE_ID 0
 
-bool isNullID(uint8_t* deviceId) {
-	return !(deviceId[0] | deviceId[1] | deviceId[2] | deviceId[3]);
-}
-
 void setup() {
 	Serial.begin(115200);
 	Serial.setTimeout(100);
@@ -60,9 +56,12 @@ void loop() {
 			Serial.println(F("Set DeviceID to: "));
 			CLP::printDeviceID(newDeviceID);
 			Serial.println();
-			if (isNullID(newDeviceID)) {
+			if (CLP::isNullID(newDeviceID)) {
 				Serial.println(F("This is a special DeviceID, it will generate a new random DeviceID next time iCUE controls the device!"));
 			}
+			if (CLP::isResetID(newDeviceID)) {
+				Serial.println(F("This is a special DeviceID, it will reset the device and then generate a new DeviceID!"));
+			}
 			Serial.println();
 			EEPROM.put(EEPROM_ADDRESS_DEVICE_ID, newDeviceID);
 		}

examples/HoodLoader2CLPBridge/CLPUSBSerialBridge.cpp

@@ -27,6 +27,11 @@ void resetIOMCU() {
 #endif // DEBUG
 }
 
+CLPUSBSerialBridge::CLPUSBSerialBridge(const char* serialNumber)
+{
+	RawHID.setSerialNumber(serialNumber);
+}
+
 void CLPUSBSerialBridge::begin()
 {
 	Serial1.begin(SERIAL_BAUD);

examples/HoodLoader2CLPBridge/CLPUSBSerialBridge.h

@@ -30,7 +30,25 @@
 
 class CLPUSBSerialBridge {
 public:
+	/**
+	 * Create a new CLPUSBSerialBridge with the default Serial Number.
+	 */
+	CLPUSBSerialBridge() {};
+	/**
+	 * Create a new CLPUSBSerialBridge and set a Serial Number.
+	 *
+	 * @param serialNumber the Serial Number of the USB device
+	 */
+	CLPUSBSerialBridge(const char* serialNumber);
+	/**
+	 * Setup the bridge connections. 
+	 * Must be called in the Arduino setup function.
+	 */
 	virtual void begin();
+	/**
+	 * Reads data from USB and sents it via Serial to the main MCU. Wait for the response and set it back to the USB host.
+	 * MUST be called in the Arduino loop function.
+	 */
 	virtual void handleHID();
 private:
 	byte rawHIDAndSerialBuffer[RAWHID_AND_SERIAL_BUFFER_SIZE];

examples/HoodLoader2CLPBridge/board.txt

@@ -1,11 +1,6 @@
 # CorsairLightingProtocol build property overrides
-#
-
-##############################################################
 
 build.vid=0x1b1c
 build.pid=0x0c0b
 build.usb_product="Lighting Node PRO"
 build.usb_manufacturer="Corsair"
-
-#build.extra_flags={build.usb_flags} '-DSERIAL_NUMBER="FB66DF55421900F5"'

examples/HoodLoader2UnoMegaController/HoodLoader2UnoMegaController.ino

@@ -16,7 +16,8 @@
 #include <CorsairLightingProtocol.h>
 #include <FastLED.h>
 
-#define CHANNEL_LED_COUNT 96
+// Hint: The Arduino Uno does not have as much memory as the Arduino Mega, it may be that problems occur when a higher value is set here.
+#define CHANNEL_LED_COUNT 60
 
 #define DATA_PIN_CHANNEL_1 2
 #define DATA_PIN_CHANNEL_2 3