ADC partly documented

README.md

@@ -18,8 +18,8 @@ This repository specifies the control protocol implemented by [gex-core](https:/
 - [UNIT_SPI.md](UNIT_SPI.md) - SPI master with up to 16 slaves and multicast
 - [UNIT_FCAP.md](UNIT_FCAP.md) - Frequency, pulse length, PWM measurement; Pulse counter
 - [UNIT_1WIRE.md](UNIT_1WIRE.md) - 1-Wire master (thermometers, iButton...)
-- UNIT_ADC.md - ADC with raw access, triggering, periodic capture
+- [UNIT_ADC.md](UNIT_ADC.md) - ADC with raw access, triggering, periodic capture
 - UNIT_DAC.md - DAC with DDS
-- UNIT_PWMDIM.md - Simpel PWM output
+- UNIT_PWMDIM.md - Simple PWM output
 - UNIT_TOUCH.md - Touch sense
 - UNIT_USART.md - UART/USART/RS485

UNIT_ADC.md

@@ -0,0 +1,138 @@
+# ADC - analog capture
+
+The ADC unit supports instantaneous readout, exponential averaging and isochronous
+sampling of up to 16 channels (+ two channels dedicated to a bandgap reference and the
+internal temperature sensor). The voltage reference may be used to compensate for supply
+voltage variations and achieve higher accuracy.
+
+The ADC unit has been tested to work up to 75 kSps with 1 channel on the 48 MHz
+STM32F072, higher frequencies made the system unstable. This should be possible to fix
+in a later firmware update. When sampling multiple channels, the maximal frequency
+drops as more data needs to be sent through the communication port.
+
+This unit works in a similar fashion to the frequency capture unit, having multiple
+mutually exclusive opmodes.
+
+All modes use periodic sampling; the frequency can be pre-comnfigured or set using
+a command.
+
+- direct measurement
+  - immediate read-out of the latest captured sample
+  - averaging available for lower frequencies, f < 20 kHz
+- isochronous sampling
+  - a unlimited stream of samples (use e.g. for visualisation)
+  - block capture of a fixed length
+  - level-trigger started capture with pre-trigger capture (like oscilloscope)
+
+Please note that the opmodes are mutually exclusive, e.g. it's not possible
+to read a averaged sample while streaming - the command will return a BUSY error.
+
+When a stream / block / trigger capture finishes, the unit returns to periodic sampling and direct read-out is available. This is also available when armed for trigger; trigger is implemented by checking the value of those direct samples.
+
+Channels must be configured in the unit settings, this is to claim the pins. They can be enabled/disabled using a command later.
+
+## Commands
+
+### READ_RAW (0)
+Get the last raw sample of enabled channels.
+
+*Response:*
+- u16[] - values for enabled channels, ascending order
+
+### READ_SMOOTHED (1)
+Read the averaged values of enabled channels.
+This function is not available for high sample rates on the STM32F072 due to the soft
+float overhead.
+
+*Response:*
+- float32[] - values for enabled channels, ascending order
+
+### GET_ENABLED_CHANNELS (10)
+Get numbers of all enabled channels.
+
+*Response:*
+- u8[] - numbers of all enabled channels, ascending order
+
+### GET_SAMPLE_RATE (11)
+Get the current sample rate in Hz
+
+*Response:*
+- u32 - sample rate
+
+### SETUP_TRIGGER (20)
+Configure the trigger level and other parameters.
+
+*Request:*
+- u8 - source channel number, 0-based. Must be enabled.
+- u16 - triggering level (0-4095)
+- u8 - triggering edge (1-falling, 2-rising, 3-any)
+- u32 - pre-trigger capture length (samples)
+- u32 - post-trigger capture length (samples)
+- u16 - hold-off time (milliseconds)
+- u8 - auto re-arm (0,1) after hold-off
+
+The trigger is not armed, only configured. Use the `ARM` command to arm.
+This is so the user can manually re-arm without sending the configuration again.
+
+### ARM (21)
+Arm the configured trigger. If already armed, do nothing.
+
+*Request:*
+- u8 - auto re-arm (0,1) after hold-off.
+  - 0xFF (255) = no change
+
+### DISARM (22)
+Dis-arm the trigger.
+
+### ABORT (23)
+Abort any ongoing capture and dis-arm the trigger.
+
+### FORCE_TRIGGER (24)
+Manually set off the triggering condition. This is useful for testing the pre-trigger
+configuration.
+
+### BLOCK_CAPTURE (25)
+Start a manual block capture. This is similar to `FORCE_TRIGGER`, but includes no pre-trigger and the length is defined in the command.
+
+*Request:*
+- u32 - number of samples to capture
+
+### STREAM_START (26)
+Start a capture stream using the current sample rate and other settings.
+
+### STREAM_STOP (27)
+Stop a stream. This is effectively equivalent to `ABORT`, but only allowed when
+a stream is running.
+
+### SET_SMOOTHING_FACTOR (28)
+Set the exponential averaging smoothing factor.
+See the unit settings for the formula.
+
+*Request:*
+- u16 - factor 0-1000, equivalent to 0.0-1.0
+
+### SET_SAMPLE_RATE (29)
+Set the sampling frequency.
+
+*Request:*
+- u32 - frequency in Hz
+
+### ENABLE_CHANNELS (30)
+Select chanbnels to enable.
+
+*Request:*
+- u32 - bit-map of the enabled channels (bits numbered from LSB=0)
+
+### SET_SAMPLE_TIME (31)
+Set sampling time. This is the time the ADC waits for the internal sampling capacitor
+to charge before starting the SAR algorithm. Shorter times should in theory allow faster
+sample rates, but since the main bottleneck here is the communicaton port, this doesn't
+have much consequence and setting it too short only degrades performance with no
+benefits.
+
+*Request:*
+- u8 - sample time 0-7 (see the STM32F072 reference manual for details)
+
+## Events
+
+...