LuaHID

LuaHID provides an interface to access USB devices over the HID (human input device) protocol. It implements a thin LUA wrapper interface over the cross platform hidapi library (hidapi.dll, see signal11/hidapi (github.com), licensed under BSD License). The code is derived from ynezz/luahidapi (github.com) (MIT License) and adopted to OGS.

Note, that although USB mice and keyboards are technically HID devices, the Windows API does not allow to access these through the HID API (for security reasons). All other (custom) USB HID devices should work.

Module

The LuaHID module provides global functions to access the systems HID API. Before calling any other function of the module, the init() function must be called.

To actually connect to a physical device, an instance of the HidDevice object must be created (see #class_hiddevice below) by calling the open() function. This requires specifying the VID (vendor ID) and PID (device id) and (optionally) the SN (serial number). If the parameters are not known beforehand, they may be listed through calling the module level enumerate() function. This returns a table of all currently connected devices. Specific device actions (like reading/writing) can then be executed on the object returned from the open() call.

Properties

Property Name	Return Type	Description	Tags
_VERSION	string	Current version of the LuaHID module. See also the version_mod() function to get more details about the DLL module version.	Read-Only
_TIMESTAMP	string	Timestamp of the last build of the LuaHID module.	Read-Only

Functions

Function Name	Return Type	Description	Tags
init()	boolean	Initializes the LuaHID library. Returns true on success, nil on failure.	None
exit()	boolean	Cleans up and terminates the LuaHID library. Returns true on success, nil on failure.	None
enumerate(integer vid, integer pid) enumerate()	hidenum	Returns a HID device enumeration object for HID devices that matches given vid, pid pair. Enumerates all HID devices if no arguments provided or (0,0) used. IMPORTANT: Mouse and keyboard devices are not visible on Windows Returns nil if failed.	None
open(string path) open(number vid, number pid)	HidDevice	Opens a HID device using a path name or a vid,pid pair. Returns a HID device object on success - specifying a serial number is currently not implemented. Returns nil on failure.	None
write(HidDevice dev, string report) write(HidDevice dev, integer report_id, string report)	integer	Writes the given report data string to the report_id (0 by default). Returns number of bytes actually sent on success, nil on failure.	None
read(HidDevice dev, integer report_size [, timeout_msec])	string	Reads data from the given device. If a device has multiple reports, the first byte indicates the report ID and one extra byte needs to be allocated via report_size. For a normal call, timeout_msec can be omitted and blocking will depend on the selected option setting. Passing timeout_msec == -1 will always block. Returns the report data (as string) on success, nil on failure.	None
set(HidDevice dev, string option)	integer	Set the read blocking option, allowed parameters are noblock and block. Returns true on success, nil on failure.	None
getstring(HidDevice dev, string option)	string	Reads the given option property from the device. Currently known option names are manufacturer, product and serial. Returns the option value on success, nil on failure.	None
setfeature(HidDevice dev, integer feature_id, string data)	integer	Send a feature report for the given feature_id with the given feature_data. Returns the number of bytes actually sent on success, nil on failure.	None
getfeature(HidDevice dev, integer feature_id, integer feature_size)	string	Get (read) a feature report for the given feature_id. A 0 is used for a single feature report. Returns the feature data (as a string) on success, nil on failure.	None
error(HidDevice dev)	string	Returns a string (as ASCII) describing the last error occurred for the device or nil if there was no error.	None
close(HidDevice dev)	None	Closes the given HidDevice object.	None
msleep(integer milliseconds)	None	Convenience function to sleep a number of milliseconds.	None
version_mod()	string, table	Returns the file version info of the LuaHID DLL (as a string in the from "major.minor.build-hi,build-low" and a table with the same values.	None

Class HidDeviceInfo

The HidDeviceInfo table provides information about a USB HID device connected to the system. The HidDeviceInfo is retrieved by calling the enumerate() function and iterating the result by calling the next() member.

Properties

Property Name	Return Type	Description	Tags
path	string	System specific device path.	Read-Only
vid	integer	Vendor ID of the device.	Read-Only
pid	integer	Product ID of the device.	Read-Only
serial_number	string	Device serial number.	Read-Only
release	integer	Release number (version) of the device.	Read-Only
manufacturer_string	string	Manufacturer name.	Read-Only
product_ _string	string	Product name.	Read-Only
usage_page	integer	HID usage page of the device.	Read-Only
usage	integer	HID usage of the device.	Read-Only
interface	integer	Interface number of the device.	Read-Only

Class HidEnum

The HidEnum class is actually an iterator and represents the list returned from calling the enumerate module function. Each element of the list represents a connected USB HID device and has the properties shown in the following section. To iterate the list, call the next() instance function - each call to next returns a HidDeviceInfo table and internally advances to the next item.

Functions

Function Name	Return Type	Description	Tags
next()	HidDevice	Returns the current device info data and steps on to the next element in the list.	None
close()	None	Closes the iterator and frees any resources. There is normally no need to call this, as the object is garbage collected automatically.	None

Class HidDevice

Functions

The member functions of HidDevice are wrapped functions of the module. The following lines are identical:

local hidapi = require('luahid')
-- ...
-- assume dev is a HidDevice object returned from calling open()
-- The following are identical:
hidapi.write(dev, report_id, report_data)
dev:write(report_id, report_data)

Function Name	Return Type	Description	Tags
write(string report) write(HidDevice dev, integer report_id, string report)	integer	See LuaHID.write(...)	None
read(integer report_size [, timeout_msec])	string	See LuaHID.read(...)	None
set(HidDevice dev, integer option)	integer	See LuaHID.set(...)	None
getstring(HidDevice dev, string option)	string	See LuaHID.getstring(...)	None
setfeature(HidDevice dev, integer feature_id, string data)	integer	See LuaHID.setfeature(...)	None
getfeature(HidDevice dev, integer feature_id, integer feature_size)	string	See LuaHID.getfeature(...)	None
error()	string	See LuaHID.error(...)	None
close(HidDevice dev)	None	See LuaHID.close(...)	None

Examples

Enumerate connected devices

This sample lists all connected HID devices and shows some of their properties.

-- Load the LuaHID module
local hidapi = require('luahid')
print(string.format("Lib VERSION %s build on %s", hid._VERSION, hid._TIMESTAMP))

-- Initialize the library
if hidapi.init() then
	print("hid library: init")
else
	print("hid library: init error")
	return
end

-- Enumerate the currently connected devices and print some information
local enum = hidapi.enumerate()
if not enum then
	print("Enumeration: no device found or enumeration failed!")
	return
else
	while true do
		local dev = enum:next()
		if not dev then break end
			print("Device found:")
			print(string.format("path = '%s'", dev.path))
			print(string.format("vid = 0x%04X", dev.vid))
			print(string.format("pid = 0x%04X", dev.pid))
			print(string.format("serial_number = '%s'", dev.serial_number))
		end
	end
end

-- Do a clean shutdown
if hidapi.exit() then
	print("hid library: exit")
else
	print("hid library: exit error")
	return
end

Read/write device report data

This sample tries to connect to a specific device using a given VID/PID and writes/reads some data in non-blocking mode.

-- Load the LuaHID module
local hidapi = require('luahid')
print(string.format("Lib VERSION %s build on %s", hid._VERSION, hid._TIMESTAMP))

-- Initialize the library
if hid.init() then
	print("hid library: init")
else
	print("hid library: init error")
	return
end

-- Open a device by VID/PID
USB_DEVICE_VID = 0x04D8
USB_DEVICE_PID = 0x8ABC
USB_REPORT_SIZE = 4
local dev = hidapi.open(USB_DEVICE_VID, USB_DEVICE_PID)
if not dev then
	print("Open: unable to open test device")
	return
end
print("Open: opened test device")

-- Read the serial number
local sn = dev:getstring("serial")
if sn then
	print("Product String: "..sn)
else
	print("Unable to read product string")
	return
end

-- set non-blocking reads
if not dev:set("noblock") then
	print("Failed to set non-blocking option")
	return
end

-- Try to read from the device. There shoud be no
-- data here, but execution should not block.
local rx = dev:read(USB_REPORT_SIZE)
if rx then
	print("Done non-blocking read test")
	print("Size of report read = "..#rx)
else
	print("Read error during non-blocking read test")
	return
end

-- Prepare and write report; report 0 is implied
local tx = string.char(0x12, 0x34, 0x56, 0x78)
local res = dev:write(tx)
if not res then
	print("Unable to write()")
	print("Error: "..dev:error())
	return
end

-- Try reading data
local rx
for i = 1, 10 do
	-- a non-infinite read loop
	-- since we read immediately right after writing, the device buffer
	-- will be empty, it will NAK, and an empty string is returned
	rx = dev:read(USB_REPORT_SIZE)
	if not rx then
		print("Unable to read()")
		print("Error: "..dev:error())
		return
	elseif rx == "" then
		print("Waiting...")
	else
		break
	end
	for j = 1,200000 do end -- short delay
end
if #rx > 0 then
	print("Successfully read data from device!")
end

-- Close the device
dev:close()
print("Close: closed test device")

-- Do a clean shutdown
if hidapi.exit() then
	print("hid library: exit")
else
	print("hid library: exit error")
	return
end

More samples

More samples can be found in then examples-folder in the GitHub repository at luahidapi/doc/examples at master · ynezz/luahidapi (github.com).