Merge pull request #6 from dmadison/recv-callback

Receive Callback

Author: dmadison

examples/BasicGamepad/BasicGamepad.ino

@@ -74,7 +74,4 @@ void loop() {
 
 	// Send control data to the computer
 	XInput.send();
-
-	// Receive data (player number, rumble motors, etc.)
-	XInput.receive();
 }

examples/ReceiveCallback/ReceiveCallback.ino

@@ -0,0 +1,73 @@
+/*
+ *  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:      ReceiveCallback
+ *  Description:  Shows how to set up a custom callback to process rumble or LED
+ *                data when the device receives a new USB packet from the host.
+ *
+ *  WARNING: The callback is called from within the USB ISR. Keep it short!
+ *
+ */
+
+#include <XInput.h>
+
+const uint8_t LED_Pin = LED_BUILTIN;
+const uint8_t Button_Pin = 6;
+
+void setup() {
+	pinMode(Button_Pin, INPUT_PULLUP);  // Set button pin as input w/ pullup
+
+	pinMode(LED_Pin, OUTPUT);    // Set LED pin as output
+	digitalWrite(LED_Pin, LOW);  // Turn LED off
+
+	// Set callback function. Function must have a 'void' return type
+	// and take a single uint8_t as an argument
+	XInput.setReceiveCallback(rumbleCallback);
+}
+
+void loop() {
+	boolean buttonState = digitalRead(Button_Pin);
+	
+	if(buttonState == LOW) { 
+		XInput.press(TRIGGER_RIGHT);
+	}
+	else {
+		XInput.release(TRIGGER_RIGHT);
+	}
+
+	XInput.send();
+}
+
+void rumbleCallback(uint8_t packetType) {
+	// If we have an LED packet (0x01), do nothing
+	if (packetType == (uint8_t) XInputReceiveType::LEDs) {
+		return;
+	}
+
+	// If we have a rumble packet (0x00), see our rumble data on the LED
+	else if (packetType == (uint8_t) XInputReceiveType::Rumble) {
+		uint8_t rumbleValue = XInput.getRumbleLeft() | XInput.getRumbleRight();
+		analogWrite(LED_Pin, rumbleValue);
+	}
+}

examples/TestAll/TestAll.ino

@@ -135,7 +135,4 @@ void loop() {
 
 	// Send values to PC
 	XInput.send();
-
-	// Receive data from PC
-	XInput.receive();
 }

examples/WiiClassicController/WiiClassicController.ino

@@ -77,5 +77,4 @@ void loop() {
 	}
 
 	XInput.send();
-	XInput.receive();
 }

keywords.txt

@@ -14,6 +14,7 @@ XInputGamepad	KEYWORD1
 
 # Enums
 XInputControl	KEYWORD1
+XInputReceiveType	KEYWORD1
 XInputLEDPattern	KEYWORD1
 
 #######################################
@@ -43,8 +44,9 @@ getPlayer	KEYWORD2
 getRumble	KEYWORD2
 getRumbleLeft	KEYWORD2
 getRumbleRight	KEYWORD2
+getLEDPattern	KEYWORD2
 
-getLEDPatternID	KEYWORD2
+setReceiveCallback	KEYWORD2
 
 # USB I/O
 connected	KEYWORD2
@@ -89,6 +91,10 @@ TRIGGER_RIGHT	LITERAL1
 JOY_LEFT	LITERAL1
 JOY_RIGHT	LITERAL1
 
+# USB Receive Packet Types
+Rumble	LITERAL1
+LEDs	LITERAL1
+
 # LED Patterns
 Off	LITERAL1
 Blinking	LITERAL1

src/XInput.cpp

@@ -167,6 +167,16 @@ struct XInputMap_Rumble {
 static const XInputMap_Rumble RumbleLeft(3, 0);   // Large motor
 static const XInputMap_Rumble RumbleRight(4, 1);  // Small motor
 
+// --------------------------------------------------------
+// XInput USB Receive Callback                            |
+// --------------------------------------------------------
+
+#ifdef USB_XINPUT
+static void XInputLib_Receive_Callback() {
+	XInput.receive();
+}
+#endif
+
 
 // --------------------------------------------------------
 // XInputGamepad Class (API)                              |
@@ -176,6 +186,9 @@ XInputGamepad::XInputGamepad() :
 	tx(), rumble() // Zero initialize arrays
 {
 	reset();
+#ifdef USB_XINPUT
+	XInputUSB::setRecvCallback(XInputLib_Receive_Callback);
+#endif
 }
 
 void XInputGamepad::press(XInputControl button) {
@@ -300,8 +313,8 @@ XInputLEDPattern XInputGamepad::getLEDPattern() const {
 	return ledPattern;
 }
 
-uint8_t XInputGamepad::getLEDPatternID() const {
-	return (uint8_t)ledPattern;
+void XInputGamepad::setReceiveCallback(RecvCallbackType cback) {
+	recvCallback = cback;
 }
 
 boolean XInputGamepad::connected() {
@@ -334,16 +347,24 @@ size_t XInputGamepad::receive() {
 	// Grab packet and store it in rx array
 	uint8_t rx[8];
 	size_t bytesRecv = XInputUSB::recv(rx, USB_Timeout);
+
+	const uint8_t PacketType = rx[0];
 
 	// Rumble Packet
-	if ((rx[0] == 0x00) & (rx[1] == 0x08)) {
+	if(PacketType == (uint8_t) XInputReceiveType::Rumble) {
 		rumble[RumbleLeft.bufferIndex]  = rx[RumbleLeft.rxIndex];   // Big weight (Left grip)
 		rumble[RumbleRight.bufferIndex] = rx[RumbleRight.rxIndex];  // Small weight (Right grip)
 	}
 	// LED Packet
-	else if (rx[0] == 0x01) {
+	else if (PacketType == (uint8_t) XInputReceiveType::LEDs) {
 		parseLED(rx[2]);
 	}
+
+	// User-defined receive callback
+	if (recvCallback != nullptr) {
+		recvCallback(PacketType);
+	}
+
 	return bytesRecv;
 #else
 	return 0;
@@ -431,6 +452,9 @@ void XInputGamepad::reset() {
 	// Reset rescale ranges
 	setTriggerRange(XInputMap_Trigger::range.min, XInputMap_Trigger::range.max);
 	setJoystickRange(XInputMap_Joystick::range.min, XInputMap_Joystick::range.max);
+
+	// Clear user-set receive callback
+	recvCallback = nullptr;
 }
 
 void XInputGamepad::printDebug(Print &output) const {

src/XInput.h

@@ -51,6 +51,11 @@ enum XInputControl {
 	JOY_RIGHT,
 };
 
+enum class XInputReceiveType {
+	Rumble = 0x00,
+	LEDs = 0x01,
+};
+
 enum class XInputLEDPattern {
 	Off = 0x00,
 	Blinking = 0x01,
@@ -96,13 +101,17 @@ class XInputGamepad {
 
 	// Received Data
 	uint8_t getPlayer() const;  // Player # assigned to the controller (0 is unassigned)
+
 	uint16_t getRumble() const;  // Rumble motors. MSB is large weight, LSB is small
-	uint8_t getRumbleLeft() const;  // Large rumble motor, left grip
-	uint8_t getRumbleRight() const; // Small rumble motor, right grip
-	
-	uint8_t getLEDPatternID() const;  // Returns LED pattern ID #
+	uint8_t  getRumbleLeft() const;  // Large rumble motor, left grip
+	uint8_t  getRumbleRight() const; // Small rumble motor, right grip
+
 	XInputLEDPattern getLEDPattern() const;  // Returns LED pattern type
 
+	// Received Data Callback
+	using RecvCallbackType = void(*)(uint8_t packetType);
+	void setReceiveCallback(RecvCallbackType);
+
 	// USB IO
 	boolean connected();
 	size_t send();
@@ -126,6 +135,7 @@ class XInputGamepad {
 	uint8_t tx[20];  // USB transmit data
 	boolean newData;  // Flag for tx data changed
 
+	RecvCallbackType recvCallback;
 	uint8_t player;  // Gamepad player #, buffered
 	uint8_t rumble[2];  // Rumble motor data in, buffered
 	XInputLEDPattern ledPattern;  // LED pattern data in, buffered