improve doc; put example in a directory

Author: dhalbert

adafruit_radial_controller/__init__.py

@@ -18,6 +18,7 @@
   At the minimum, a radial controller is a rotary encoder plus a switch.
 
   Documentation is available from Microsoft:
+  https://docs.microsoft.com/en-us/windows-hardware/design/component-guidelines/radial-implementation-guide
 
 **Software and Dependencies:**
 
@@ -77,8 +78,10 @@ def click(self):
 
     def rotate(self, degree_tenths):
         """Set relative rotation value, in tenths of a degree.
-        A value of 1 or 10 can be too small and cause tool selection or scrolling to not work.
-        100 is a good value for a single increment in most cases."""
+        A value of +/- 1 or 10 can be too small and cause tool selection or scrolling to not work.
+        +/- 100 is a good value for a single increment in many cases, though it causes value sliders
+        to change by 10 instead of 1.
+        """
 
         if not -3600 <= degree_tenths <= 3600:
             raise ValueError("rotation must be in range -3600 to 3600")

adafruit_radial_controller/device.py

@@ -69,8 +69,9 @@ def device(report_id):
             0xc0,             #   End Collection
             0xc0,             # End Collection
 
-            # The presence of this (even empty) System Control Collection makes the device
-            # appears in /dev/input in Linux. Don't know why this works yet.
+            # The presence of this (empty) System Control Collection makes the device
+            # appear in /dev/input in Linux, which will help if radial controller
+            # functionality is added in userspace code.
             0x09, 0x80,       # Usage (System Control)
             0xa1, 0x01,       # Collection (Application)
             0xc0,             # End Collection

examples/radial_controller_rotary_trinkey/boot.py

@@ -0,0 +1,12 @@
+# SPDX-FileCopyrightText: Copyright (c) 2021 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: Unlicense
+
+import usb_hid
+
+import adafruit_radial_controller.device
+
+REPORT_ID = 5
+
+radial_controller_device = adafruit_radial_controller.device.device(REPORT_ID)
+usb_hid.enable((radial_controller_device,))

examples/radial_controller_rotary_trinkey/code.py

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: Copyright (c) 2021 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: Unlicense
+
+import board
+import digitalio
+import rotaryio
+import usb_hid
+
+from adafruit_debouncer import Debouncer
+import adafruit_radial_controller
+
+switch = digitalio.DigitalInOut(board.SWITCH)
+switch.pull = digitalio.Pull.DOWN
+debounced_switch = Debouncer(switch)
+
+encoder = rotaryio.IncrementalEncoder(board.ROTA, board.ROTB)
+
+radial_controller = adafruit_radial_controller.RadialController(usb_hid.devices)
+
+last_position = 0
+DEGREE_TENTHS_MULTIPLIER = 100
+
+while True:
+    debounced_switch.update()
+    if debounced_switch.rose:
+        radial_controller.press()
+    if debounced_switch.fell:
+        radial_controller.release()
+
+    position = encoder.position
+    delta = position - last_position
+    if delta != 0:
+        radial_controller.rotate(delta * DEGREE_TENTHS_MULTIPLIER)
+        last_position = position