README.md 3.2 KB
Newer Older
phil's avatar
phil committed
1
2
# hid-pd-external

phil's avatar
phil committed
3
An USB HID external for PureData (PD)
phil's avatar
phil committed
4

phil's avatar
phil committed
5
6
7
8
*Note* the current version only outputs raw values as received from the HID -
HID descriptor input item specifics (such as min/max, units, exponentials, etc)
are not respected. This is not yet implemented in the underlaying [USB-HID-Report-Parser](https://github.com/tschiemer/USB-HID-Report-Parser/tree/usbhid_map).

phil's avatar
phil committed
9
10
11
Built and tested on macos 10.15.7.
Tested RPi 4 (5.10.17-v7l+), in principle works but is suboptimal.

phil's avatar
phil committed
12
13
![hid-example.pd](hid-example.pd.png)

phil's avatar
phil committed
14
## Todos
phil's avatar
phil committed
15
16
17
18
19

- [ ] Add output report support
- [ ] Feature reports?
- [ ] Use hidraw instead of libusb (see note under linux)

phil's avatar
phil committed
20
21
22
23
## Binaries

See https://github.com/tschiemer/hid-pd-external/releases

phil's avatar
phil committed
24
25
26
27
## Building

### macos

28
29
30
31
Install dependencies:
```bash
brew install libusb hidapi
```
phil's avatar
phil committed
32

33
Compile:
phil's avatar
phil committed
34
```bash
phil's avatar
phil committed
35
36
37
38
39
40
41
git clone --recursive https://github.com/tschiemer/hid-pd-external
cd hid-pd-external/
make -f Makefile.macos && make -f Makefile.macos install
```

### linux (Raspberry Pi)

phil's avatar
phil committed
42
*NOTE* as it is, using libusb (in this external) on linux is somewhat invasive on USB devices as kernel
phil's avatar
phil committed
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
drivers might be detached for this to work. Using hidraw (as offered by hidapi) this seems to work without
further problem, but this is something that remains to be done.

Make sure to install required libraries:

```bash
sudo apt install libusb-1.0-0-dev libhidapi-dev
```

```bash
git clone --recursive https://github.com/tschiemer/hid-pd-external
cd hid-pd-external/
make -f Makefile.linux
sudo make -f Makefile.linux install
```

*NOTE* Your user will have to get direct access to HID devices, if you know which device it is, you can do something like  

```bash
sudo chmod 777 /dev/bus/usb/001/003
```

In principle you could set up [udev to do this for you](https://askubuntu.com/a/15643) (but didn't work for me).


## `hid` object interface

- `list [vendorid <vendor-id>] [productid <product-id>] [serial <serial-str>] [usage_page <usage-page>] [usage <usage>]`

Output any HID devices matching the given criteria in the form of:

`device <usage-page> <usage> <vendor-id> <product-id> <serial-str> <manufacturer-str> <product-str>`

If `serial-str`, `manufacturer-str` or `product-str` is not defined by the device will return a dash `-`.

- `open  [vendorid <vendor-id>] [productid <product-id>] [serial <serial-str>] [usage_page <usage-page>] [usage <usage>]`

Attempts to open first device matching given criteria for interaction.

Outputs `opened` message on success.

- `close`

Closes previously opened device.

- *bang* / `poll <msec>`

Output/process incoming reports and output changed values in the form of

`value <usage-page> <usage> <value>`

If polling (`<msec>` > 0) is enabled *banging* is not possible, to disable polling set `<msec>` equal zero.

## License

phil's avatar
phil committed
98
Copyright 2021 ICST Institute for Computer Music and Sound
phil's avatar
phil committed
99
100
101
102
103
Technology, Zurich University of the Arts
All rights reserved.

GNU General Public License v3

phil's avatar
phil committed
104
105
Author Philip Tschiemer, https://github.com/tschiemer

phil's avatar
phil committed
106
107
108
109
Relies on (also see [deps](deps)):
- [libusb](https://github.com/libusb/libusb)
- [hidapi](https://github.com/libusb/hidapi)
- [USB-HID-Report-Parser](https://github.com/tschiemer/USB-HID-Report-Parser/tree/usbhid_map)
phil's avatar
phil committed
110
- [pd-lib-builder](https://github.com/pure-data/pd-lib-builder)