lib: add new interfaces for HID++ communication

4 files changed, 301 insertions, 0 deletions

diff --git a/lib/hidpp.h b/lib/hidpp.h
new file mode 100644
index 0000000..3aed2eb
--- /dev/null
+++ b/lib/hidpp.h
@@ -0,0 +1,95 @@
+/*
+ * Generic HID++ definitions and helpers.
+ *
+ * Copyright (C) 2014 Peter Wu <peter@lekensteyn.nl>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef HIDPP_H
+#define HIDPP_H
+#include <stdbool.h>
+#include <stdint.h>
+
+#define MAX_DEVICES 6
+
+/* report ID for short and long HID++ messages */
+#define HIDPP_SHORT             0x10
+#define HIDPP_SHORT_LEN         7
+#define HIDPP_LONG              0x11
+#define HIDPP_LONG_LEN          20
+
+typedef struct HidppMessage {
+	uint8_t report_id;
+	uint8_t device_index;
+	union {
+		struct {
+			uint8_t sub_id;
+			uint8_t address;
+		}; /**< HID++ 1.0 naming */
+		struct {
+			uint8_t feature_id;
+			uint8_t func; /* (func << 4) | swId */
+		}; /**< HID++ 2.0 naming */
+	};
+	union {
+		uint8_t params[3];
+		uint8_t params_l[16];
+	};
+} HidppMessage;
+
+/**
+ * Locates a /dev/hidrawX device for a Logitech Unifying receiver.
+ *
+ * @return A file descriptor to the hidraw device which must be closed with
+ * close().
+ */
+int hidpp_open(void);
+
+/**
+ * Callback function for new messages.
+ *
+ * @param msg[in]   An incoming HID++ message.
+ * @param userdata  Data passed through the invoker.
+ * @return true iff the no more messages should be read.
+ */
+typedef bool hidpp_msg_cb_t(HidppMessage *msg, void *userdata);
+
+/**
+ * Sends the message to the receiver device.
+ *
+ * @param fd        File descriptor of the hidraw device.
+ * @param msg[in]   The report to be delivered.
+ * @return true iff the message is properly formatted and the dispatch is
+ * successful.
+ */
+bool hidpp_write_report(int fd, struct HidppMessage *msg);
+
+/**
+ * Reads messages and try to accept on one of them.
+ *
+ * @param fd        File descriptor of the hidraw device.
+ * @param timeout   Timeout for this function in milliseconds.
+ * @param msg[out]  On success, the message is written to this pointer.
+ *                  Otherwise, the contents are unmodified.
+ * @param cb        Function that should be called for new HID++ messages.
+ *                  If true is returned, then no more messages are read. msg is
+ *                  not allowed to be modified if the callback returns false.
+ * @param userdata  Data that is passed unchanged to the callback function.
+ * @return true iff there exists a message that was accepted by the callback
+ * function within the timeout.
+ */
+bool hidpp_read_msg(int fd, int timeout, HidppMessage *msg,
+                    hidpp_msg_cb_t *cb, void *userdata);
+#endif
diff --git a/lib/hidpp10.h b/lib/hidpp10.h
new file mode 100644
index 0000000..f8be8b0
--- /dev/null
+++ b/lib/hidpp10.h
@@ -0,0 +1,64 @@
+/*
+ * HID++ 1.0 protocol details.
+ *
+ * Copyright (C) 2014 Peter Wu <peter@lekensteyn.nl>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef HIDPP_10_H
+#define HIDPP_10_H
+#include <stdint.h>
+#include "hidpp.h"
+
+#define SUB_SET_REGISTER        0x80
+#define SUB_GET_REGISTER        0x81
+#define SUB_SET_LONG_REGISTER   0x82
+#define SUB_GET_LONG_REGISTER   0x83
+#define SUB_ERROR_MSG           0x8F
+
+#define NOTIF_DEV_DISCONNECT    0x40 /* Device Disconnection */
+#define NOTIF_DEV_CONNECT       0x41 /* Device Connection */
+#define NOTIF_RECV_LOCK_CHANGE  0x4A /* Unifying Receiver Locking Change information */
+
+#define REG_ENABLED_NOTIFS      0x00
+#define REG_CONNECTION_STATE    0x02
+/* Device Connection and Disconnection (Pairing) */
+#define REG_DEVICE_PAIRING      0xB2
+#define REG_DEVICE_ACTIVITY     0xB3
+#define REG_PAIRING_INFO        0xB5
+#define REG_VERSION_INFO        0xF1 /* undocumented */
+
+/**
+ * Attempts to dispatch a register query.
+ *
+ * @param fd        File descriptor of the hidraw device.
+ * @param msg[in,out] The message to be sent. If a matching response was
+ *                  received, then this will contain that response. Otherwise,
+ *                  it is unmodified.
+ * @param cb        Function that should be called for HID++ notifications. Its
+ *                  return value is ignored. The callback must not modify msg.
+ * @return 0 on success, a HID++ 1.0 error code otherwise.
+ */
+int hidpp10_request(int fd, HidppMessage *msg, hidpp_msg_cb_t *cb, void *userdata);
+
+/**
+ * Attempts to enable/disable reporting of wireless notifications.
+ *
+ * @param fd        File descriptor of the hidraw device.
+ * @param enabled   Whether wireless notifications should be reported.
+ * @return 0 on success, a HID++ 1.0 error code otherwise.
+ */
+int hidpp10_enable_wireless_notifications(int fd, bool enabled);
+#endif
diff --git a/lib/hidpp20.h b/lib/hidpp20.h
new file mode 100644
index 0000000..838f70c
--- /dev/null
+++ b/lib/hidpp20.h
@@ -0,0 +1,69 @@
+/*
+ * HID++ 2.0 protocol details.
+ *
+ * Copyright (C) 2014 Peter Wu <peter@lekensteyn.nl>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef HIDPP_20_H
+#define HIDPP_20_H
+#include <stdint.h>
+#include "hidpp.h"
+
+typedef struct {
+	uint8_t     feature_index;
+	uint16_t    feature_id;
+	uint8_t     feature_type;
+} FeatureInfo;
+
+/**
+ * Retrieves the number of HID++ 2.0 features.
+ *
+ * @param fd        File descriptor of the hidraw device.
+ * @param count[out] The number of HID++ 2.0 features.
+ * @return Zero on success, a HID++ error code otherwise.
+ */
+int hidpp20_get_features_count(int fd, uint8_t *count);
+
+/**
+ * Retrieves feature information from a feature index.
+ *
+ * @param fd        File descriptor of the hidraw device.
+ * @param feature_index A feature index to find information for.
+ * @param fi[out]   Feature information on success.
+ * @return Zero on success, a HID++ error code otherwise.
+ */
+int hidpp20_get_feature(int fd, uint8_t feature_index, FeatureInfo *fi);
+
+/**
+ * Retrieves the feature index for a given feature ID.
+ *
+ * @param fd        File descriptor of the hidraw device.
+ * @param feature_id A 16-bit feature identifier.
+ * @param fi[out]   Feature information on success.
+ * @return Zero on success, a HID++ error code otherwise.
+ */
+int hidpp20_get_feature_by_id(int fd, uint16_t feature_id, FeatureInfo *fi);
+
+/**
+ * Retrieves the HID++ version for the device.
+ *
+ * @param fd        File descriptor of the hidraw device.
+ * @param device_index Device index (between 1 and 6).
+ * @return a non-zero number indicating the HID++ version or 0 if the version
+ * could not be determined.
+ */
+uint16_t hidpp20_get_version(int fd, uint8_t device_index);
+#endif
diff --git a/lib/unifying.h b/lib/unifying.h
new file mode 100644
index 0000000..4306414
--- /dev/null
+++ b/lib/unifying.h
@@ -0,0 +1,73 @@
+/*
+ * Generic routines for communicating with Logitech Unifying devices.
+ *
+ * Copyright (C) 2014 Peter Wu <peter@lekensteyn.nl>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef UNIFYING_H
+#define UNIFYING_H
+#include <stdint.h>
+
+typedef struct UnifyingState UnifyingState;
+
+typedef enum {
+	FWVER_MAIN = 0, /**< Main firmware version */
+	FWVER_BL,       /**< Bootloader version */
+	FWVER_HW,       /**< Hardware version */
+} FirmwareType;
+
+typedef struct {
+	char prefix[4]; /**< Prefix of the firmware version (if any) */
+	uint8_t major;
+	uint8_t minor;
+	uint16_t build;
+} FirmwareVersion;
+
+/**
+ * Attempts to open a Unifying device.
+ *
+ * @param fd    File descriptor of the hidraw device.
+ * @return A pointer to a structure that must be released by
+ *         unifying_device_close(), or NULL on error.
+ */
+UnifyingState *unifying_new(int fd);
+
+/**
+ * Closes the file descriptor associated with this device and releases memory
+ * claimed for this structure.
+ *
+ * @param s     State to be freed.
+ */
+void unifying_close(UnifyingState *s);
+
+int unifying_rvr_get_version(UnifyingState *s, FirmwareType type,
+                             FirmwareVersion *fw);
+int unifying_rvr_get_serial(UnifyingState *s, uint32_t *serial);
+
+/* general device information */
+int unifying_dev_get_version(UnifyingState *s, uint8_t ix, FirmwareType type,
+                             FirmwareVersion *fw);
+int unifying_dev_get_short_name(UnifyingState *s, uint8_t ix, char *name);
+int unifying_dev_get_name(UnifyingState *s, uint8_t ix, char **name);
+int unifying_dev_get_wpid(UnifyingState *s, uint8_t ix, uint16_t *wpid);
+int unifying_dev_get_type(UnifyingState *s, uint8_t ix, uint8_t *devtype);
+int unifying_dev_get_serial(UnifyingState *s, uint8_t ix, uint32_t *serial);
+
+/* pairing related */
+int unifying_dev_pairing_open(UnifyingState *s);
+int unifying_dev_pairing_unpair(UnifyingState *s, uint8_t ix);
+int unifying_dev_pairing_close(UnifyingState *s);
+#endif