DI

README.md

@@ -2,9 +2,14 @@
 
 This repository specifies the control protocol implemented by [gex-core](https://github.com/gexpander/gex-core).
 
+## General information
+
 - [FRAME_FORMAT.md](FRAME_FORMAT.md) - Low level frame format, message types
 - [INTERNAL_STRUCTURE.md](INTERNAL_STRUCTURE.md) - GEX's internal structure, units, requests and events
 - [INI_FILES.md](INI_FILES.md) - INI config files, filesystem and API access
 
-- [UNIT_DO.md](UNIT_DO.md) - Digital Output unit
+## Unit types
+
+- [UNIT_DO.md](UNIT_DO.md) - Digital Output
+- [UNIT_DI.md](UNIT_DI.md) - Digital Input
 

UNIT_DI.md

@@ -0,0 +1,46 @@
+# Digital Input
+
+- Direct digital input on selected pins of a port
+- Pin change events
+
+Pins are described using the packed format (see [UNIT_DO.md](UNIT_DO.md))
+
+## Commands
+
+### READ (0x00)
+Read all pins.
+
+*Response:*
+- u16 - pin states (packed)
+
+### ARM_SINGLE (0x01)
+Arm a pin or pins for a change detection.
+The active edge is defined in the unit settings.
+The pins are dis-armed again after a detected event.
+
+*Request:*
+- u16 - pins to arm (packed)
+
+### ARM_AUTO (0x02)
+Arm a pin or pins for a change detection with automatic re-arm.
+The active edge is defined in the unit settings.
+
+*Request:*
+- u16 - pins to arm (packed)
+
+### DISARM (0x03)
+Disable change detection on the selected pins.
+
+*Request:*
+- u16 - pins to dis-arm (packed)
+
+## Events
+
+### PIN_CHANGE (0x00)
+
+External interrupt, pin change(s) detected.
+Reports which pins caused the event (can be multiple), and the entire unit's input captured right after the event.
+
+*Payload:*
+- u16 - pins that caused the event (packed)
+- u16 - port snapshot at the time of the event (packed)

UNIT_DO.md

@@ -2,37 +2,37 @@
 
 - Direct output access to one or more pins of a port.
 - All selected pins are written simultaneously.
-- Supports generating output pulses of precise length.
+- Supports generating output pulses of a precise length.
 
-Pins are ordered in a descending order (DOWNTO) and accessed in a packed format,
+Pins are ordered in a descending order (DOWNTO) and described in a packed format,
 e.g. if pins 1 and 4 are selected (`0b10010` on the port), the control word has
-two bits `(4)(1)` and e.g. `0b10` means pin 4, `0b11` both. This makes accessing the
-block of pins easier, e.g. when using them to drive a parallel bus.
+two bits `(4)(1)` and e.g. `0b10` means pin 4, `0b11` both. This makes accessing
+the block of pins easier, e.g. when using them to drive a parallel bus. For single-pin units, the control word is always `1`.
 
 ## Commands
 
 ### WRITE (0x00)
 Write a value to all defined pins.
 
-*Payload:*
+*Request:*
 - u16 - new value (packed)
 
 ### SET (0x01)
 Set pins high
 
-*Payload:*
+*Request:*
 - u16 - pins to set high (packed)
 
 ### CLEAR (0x02)
 Set pins low
 
-*Payload:*
+*Request:*
 - u16 - pins to set low (packed)
 
 ### TOGGLE (0x03)
 Toggle selected pins (high - low)
 
-*Payload:*
+*Request:*
 - u16 - pins to toggle (packed)
 
 ### PULSE (0x04)
@@ -40,7 +40,7 @@ Send a pulse.
 
 The start will be aligned to 1 us or 1 ms (based on pulse length) of the internal timebase to ensure the highest length precision. This alignment reduces jitter in the pulse duration. A jitter of the pulse start time is less significant, as there's already some unpredictable delay caused by the USB connection and the PC OS scheduler.
 
-*Payload:*
+*Request:*
 - u16 - pins to generate the pulse on (packed)
 - u8 - pulse active level (0, 1)
 - u8 - range (0 - milliseconds, 1 - microseconds)
@@ -49,6 +49,8 @@ The start will be aligned to 1 us or 1 ms (based on pulse length) of the interna
 *NOTE:* The microsecond range supports durations only up to 999 us, higher
 numbers will be divided by 1000 and use the millisecond range instead.
 
+An ongoing pulse is stopped by any command affecting the pin.
+
 ## Events
 
 *No events defined for this unit type.*