Add support for examining camera serial numbers and opening devices by camera serial number.

Since the index used in freenect_open_device() is nondeterministic, this makes
it possible to make one particular piece of hardware the "left Kinect" or the
"right Kinect" in a multi-Kinect setup.

Signed-off-by: Drew Fisher <[email protected]>

Author: zarvox

include/libfreenect.h

@@ -46,6 +46,15 @@ typedef enum {
 	FREENECT_DEVICE_AUDIO  = 0x04,
 } freenect_device_flags;
 
+/// A struct used in enumeration to give access to serial numbers, so you can
+/// open a particular device by serial rather than depending on index.  This
+/// is most useful if you have more than one Kinect.
+struct freenect_device_attributes;
+struct freenect_device_attributes {
+	struct freenect_device_attributes *next; /**< Next device in the linked list */
+	const char* camera_serial; /**< Serial number of this device's camera subdevice */
+};
+
 /// Enumeration of available resolutions.
 /// Not all available resolutions are actually supported for all video formats.
 /// Frame modes may not perfectly match resolutions.  For instance,
@@ -232,6 +241,25 @@ FREENECTAPI int freenect_process_events(freenect_context *ctx);
  */
 FREENECTAPI int freenect_num_devices(freenect_context *ctx);
 
+/**
+ * Scans for kinect devices and produces a linked list of their attributes
+ * (namely, serial numbers), returning the number of devices.
+ *
+ * @param ctx Context to scan for kinect devices with
+ * @param attribute_list Pointer to where this function will store the resultant linked list
+ *
+ * @return Number of devices connected, < 0 on error
+ */
+FREENECTAPI int freenect_list_device_attributes(freenect_context *ctx, struct freenect_device_attributes** attribute_list);
+
+/**
+ * Free the linked list produced by freenect_list_device_attributes().
+ *
+ * @param ctx Context from which the list was allocated
+ * @param attribute_list Linked list of attributes to free.
+ */
+FREENECTAPI void freenect_free_device_attributes(struct freenect_device_attributes* attribute_list);
+
 /**
  * Set which subdevices any subsequent calls to freenect_open_device()
  * should open.  This will not affect devices which have already been
@@ -257,6 +285,19 @@ FREENECTAPI void freenect_select_subdevices(freenect_context *ctx, freenect_devi
  */
 FREENECTAPI int freenect_open_device(freenect_context *ctx, freenect_device **dev, int index);
 
+/**
+ * Opens a kinect device (via a context) associated with a particular camera
+ * subdevice serial number.  This function will fail if no device with a
+ * matching serial number is found.
+ *
+ * @param ctx Context to open device through
+ * @param dev Device structure to assign opened device to
+ * @param camera_serial Null-terminated ASCII string containing the serial number of the camera subdevice in the device to open
+ *
+ * @return 0 on success, < 0 on error
+ */
+FREENECTAPI int freenect_open_device_by_camera_serial(freenect_context *ctx, freenect_device **dev, const char* camera_serial);
+
 /**
  * Closes a device that is currently open
  *

src/core.c

@@ -77,6 +77,27 @@ FREENECTAPI int freenect_num_devices(freenect_context *ctx)
 	return fnusb_num_devices(&ctx->usb);
 }
 
+FREENECTAPI int freenect_list_device_attributes(freenect_context *ctx, struct freenect_device_attributes **attribute_list)
+{
+	return fnusb_list_device_attributes(&ctx->usb, attribute_list);
+}
+
+FREENECTAPI void freenect_free_device_attributes(struct freenect_device_attributes *attribute_list)
+{
+	// Iterate over list, freeing contents of each item as we go.
+	struct freenect_device_attributes* to_free;
+	while(attribute_list != NULL) {
+		to_free = attribute_list;
+		if (attribute_list->camera_serial != NULL) {
+			free((char*)attribute_list->camera_serial);
+			attribute_list->camera_serial = NULL;
+		}
+		attribute_list = attribute_list->next;
+		free(to_free);
+	}
+	return;
+}
+
 FREENECTAPI void freenect_select_subdevices(freenect_context *ctx, freenect_device_flags subdevs) {
 	ctx->enabled_subdevices = (freenect_device_flags)(subdevs & (FREENECT_DEVICE_MOTOR | FREENECT_DEVICE_CAMERA
 #ifdef BUILD_AUDIO
@@ -123,6 +144,30 @@ FREENECTAPI int freenect_open_device(freenect_context *ctx, freenect_device **de
 	return 0;
 }
 
+FREENECTAPI int freenect_open_device_by_camera_serial(freenect_context *ctx, freenect_device **dev, const char* camera_serial)
+{
+	// This is implemented by listing the devices and seeing which index (if
+	// any) has a camera with a matching serial number, and then punting to
+	// freenect_open_device with that index.
+	struct freenect_device_attributes* attrlist;
+	struct freenect_device_attributes* item;
+	int count = fnusb_list_device_attributes(&ctx->usb, &attrlist);
+	if (count < 0) {
+		FN_ERROR("freenect_open_device_by_camera_serial: Couldn't enumerate serial numbers\n");
+		return -1;
+	}
+	int index = 0;
+	for(item = attrlist ; item != NULL; item = item->next , index++) {
+		if (strlen(item->camera_serial) == strlen(camera_serial) && strcmp(item->camera_serial, camera_serial) == 0) {
+			freenect_free_device_attributes(attrlist);
+			return freenect_open_device(ctx, dev, index);
+		}
+	}
+	freenect_free_device_attributes(attrlist);
+	FN_ERROR("freenect_open_device_by_camera_serial: Couldn't find a device with serial %s\n", camera_serial);
+	return -1;
+}
+
 FREENECTAPI int freenect_close_device(freenect_device *dev)
 {
 	freenect_context *ctx = dev->parent;

src/usb_libusb10.c

@@ -56,6 +56,66 @@ int fnusb_num_devices(fnusb_ctx *ctx)
 	return nr;
 }
 
+int fnusb_list_device_attributes(fnusb_ctx *ctx, struct freenect_device_attributes** attribute_list)
+{
+	*attribute_list = NULL; // initialize some return value in case the user is careless.
+	libusb_device **devs;
+	//pointer to pointer of device, used to retrieve a list of devices
+	ssize_t count = libusb_get_device_list (ctx->ctx, &devs);
+	if (count < 0)
+		return -1;
+
+	struct freenect_device_attributes** camera_prev_next = attribute_list;
+
+	// Pass over the list.  For each camera seen, if we already have a camera
+	// for the newest_camera device, allocate a new one and append it to the list,
+	// incrementing num_devs.  Likewise for each audio device.
+	struct libusb_device_descriptor desc;
+	int num_cams = 0;
+	int i;
+	for (i = 0; i < count; i++) {
+		int r = libusb_get_device_descriptor (devs[i], &desc);
+		if (r < 0)
+			continue;
+		if (desc.idVendor == VID_MICROSOFT && desc.idProduct == PID_NUI_CAMERA) {
+			// Verify that a serial number exists to query.  If not, don't touch the device.
+			if (desc.iSerialNumber == 0) {
+				continue;
+			}
+
+			// Open device.
+			int res;
+			libusb_device_handle *this_device;
+			res = libusb_open(devs[i], &this_device);
+			unsigned char string_desc[256]; // String descriptors are at most 256 bytes.
+			if (res != 0) {
+				continue;
+			}
+
+			// Read string descriptor referring to serial number.
+			res = libusb_get_string_descriptor_ascii(this_device, desc.iSerialNumber, string_desc, 256);
+			libusb_close(this_device);
+			if (res < 0) {
+				continue;
+			}
+
+			// Add item to linked list.
+			struct freenect_device_attributes* new_dev_attrs = (struct freenect_device_attributes*)malloc(sizeof(struct freenect_device_attributes));
+			memset(new_dev_attrs, 0, sizeof(*new_dev_attrs));
+
+			*camera_prev_next = new_dev_attrs;
+			// Copy string with serial number
+			new_dev_attrs->camera_serial = strdup((char*)string_desc);
+			camera_prev_next = &(new_dev_attrs->next);
+			// Increment number of cameras found
+			num_cams++;
+		}
+	}
+
+	libusb_free_device_list(devs, 1);
+	return num_cams;
+}
+
 int fnusb_init(fnusb_ctx *ctx, freenect_usb_context *usb_ctx)
 {
 	int res;

src/usb_libusb10.h

@@ -84,6 +84,7 @@ typedef struct {
 } fnusb_isoc_stream;
 
 int fnusb_num_devices(fnusb_ctx *ctx);
+int fnusb_list_device_attributes(fnusb_ctx *ctx, struct freenect_device_attributes** attribute_list);
 
 int fnusb_init(fnusb_ctx *ctx, freenect_usb_context *usb_ctx);
 int fnusb_shutdown(fnusb_ctx *ctx);