Merge pull request #14 from dmadison/api-example

USB API Example

Author: dmadison

extras/API-Demo/API-Demo.ino

@@ -0,0 +1,91 @@
+/*
+ *  Project     Arduino XInput Library
+ *  @author     David Madison
+ *  @link       github.com/dmadison/ArduinoXInput
+ *  @license    MIT - Copyright (c) 2019 David Madison
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ *  Example:      API Demo
+ *  Description:  Tests for the functionality of the XInputUSB API
+ *                without using the Arduino XInput library. Useful
+ *                for testing boards packages without the library
+ *                as a factor.
+ *
+ *                Tests the following XInputUSB functions:
+ *                  * static boolean connected(void)
+ *                  * static uint8_t available(void)
+ *                  * static int send(const void *buffer, uint8_t nbytes)
+ *                  * static int recv(void *buffer, uint8_t nbytes)
+ *                  * static void setRecvCallback(void(*callback)(void))
+ *
+ *                If the example is running properly, the controller's
+ *                'A' button should toggle on and off every 2 seconds
+ *                and the built-in LED should turn on when rumble data
+ *                is received.
+ */
+
+#ifndef USB_XINPUT
+#error "USB_XINPUT not defined! No XInput API detected"
+#else
+
+uint8_t txData[20] = { 0x00, 0x14, 0x00 };
+boolean buttonState = false;
+
+void setup() {
+	pinMode(LED_BUILTIN, OUTPUT);
+	digitalWrite(LED_BUILTIN, LOW);
+
+	while (!XInputUSB::connected()) {}  // wait for connection
+	XInputUSB::setRecvCallback(receiveCallback);
+}
+
+void loop() {
+	buttonState = !buttonState;
+	setButtonA(txData, buttonState);
+	XInputUSB::send(txData, sizeof(txData));
+	
+	delay(1000);
+}
+
+void setButtonA(uint8_t * ptr, boolean state) {
+	const uint8_t ButtonIndex = 3;
+	const uint8_t ButtonPosition = 4;
+
+	if (state == true) {
+		ptr[ButtonIndex] |= (1 << ButtonPosition);
+	}
+	else {
+		ptr[ButtonIndex] &= ~(1 << ButtonPosition);
+	}
+}
+
+void receiveCallback() {
+	if (XInputUSB::available() > 0) {
+		uint8_t rxData[8] = { 0x00 };
+		const int success = XInputUSB::recv(rxData, sizeof(rxData));
+
+		if (success > 5 && rxData[0] == 0x00) {  // rumble packet
+			boolean rumbling = (rxData[3] > 0 || rxData[4] > 0 );
+			digitalWrite(LED_BUILTIN, rumbling);
+		}
+	}
+}
+
+#endif

extras/XInputUSB_API.md

@@ -19,7 +19,7 @@ Here is the C++ API header in all of its glory:
 
 class XInputUSB {
 public:
-	static bool connected(void);
+	static boolean connected(void);
 	static uint8_t available(void);
 	static int send(const void *buffer, uint8_t nbytes);
 	static int recv(void *buffer, uint8_t nbytes);
@@ -33,7 +33,7 @@ Note the `USB_XINPUT` preprocessor definition. This definition is what tells the
 
 The API consists of five core static functions of the `XInputUSB` class that pass the USB data back and forth from the bus to the library. Here is the breakdown:
 
-### bool connected(void)
+### boolean connected(void)
 
 The `connected` function returns the state of the USB interface with respect to XInput. If the device is connected to a host and functional this should return `true`. If the device is disconnected this should return `false`.
 
@@ -84,3 +84,5 @@ Here are my two API implementations for reference:
 
 * [Arduino AVR Boards](https://github.com/dmadison/ArduinoXInput_AVR/blob/master/cores/arduino/xinput/USB_XInput_API.cpp)
 * [Teensy 3 Boards](https://github.com/dmadison/ArduinoXInput_Teensy/blob/master/teensy/avr/cores/teensy3/usb_xinput.c)
+
+I've also included a test sketch for validating an XInputUSB API implementation without the library, which you can find [here](API-Demo/API-Demo.ino).