From 7cff1e27b7c2b570b73b1e1ce036336440112b9c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ond=C5=99ej=20Hru=C5=A1ka?= <ondra@ondrovo.com>
Date: Wed, 28 Mar 2018 00:33:51 +0200
Subject: [PATCH] DAC

---
 README.md   |  2 +-
 UNIT_DAC.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 94 insertions(+), 1 deletion(-)
 create mode 100644 UNIT_DAC.md

diff --git a/README.md b/README.md
index 722e07f..563b250 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,7 @@ This repository specifies the control protocol implemented by [gex-core](https:/
 - [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](UNIT_ADC.md) - ADC with raw access, triggering, periodic capture
-- UNIT_DAC.md - DAC with DDS
+- [UNIT_DAC.md](UNIT_DAC.md) - DAC with DDS
 - UNIT_PWMDIM.md - Simple PWM output
 - UNIT_TOUCH.md - Touch sense
 - UNIT_USART.md - UART/USART/RS485
diff --git a/UNIT_DAC.md b/UNIT_DAC.md
new file mode 100644
index 0000000..5f06d73
--- /dev/null
+++ b/UNIT_DAC.md
@@ -0,0 +1,93 @@
+# DAC - analog output
+
+The DAC unit has two analog outputs and can either output a DC level, or one of the pre-defined waveforms. Those waveforms are generated using a DDS principle, the numerical equivalent of a PLL.
+
+- DC
+- SINE
+- TRIANGLE
+- SAWTOOTH UP
+- SAWTOOTH DOWN
+- RECTANGLE
+
+The DDS output speed is limited by the processor speed; properly shaped waveforms can
+be generated up to tens of kHz, obviously a better resolution is achieved with slower waveforms.
+
+DDS provides a very precise frequency adjustment at the expense of jitter. Faster frequencies tend to became more "pixelated" as there are fewer counter steps per period.
+
+The ADC unit further supports dithering using a noise generator and a sawtooth wave,
+provided by the STM32's hardware. Those are used e.g. to increase ADC resolution by introducing artificial noise through a large resistor.
+
+## Commands
+
+### WAVE_DC (0)
+Set a DC level, disable DDS for the channel
+
+*Request:*
+- u8 - channels (1-first, 2-second, 3-both)
+- u16 - level 0-4095
+
+### WAVE_SINE (1)
+Start a DDS sine waveform
+
+*Request:*
+- u8 - channels (1-first, 2-second, 3-both)
+
+### WAVE_TRIANGLE (2)
+Start a symmetrical triangle waveform
+
+*Request:*
+- u8 - channels (1-first, 2-second, 3-both)
+
+### WAVE_SAWTOOTH_UP (3)
+Start a rising sawtooth
+
+*Request:*
+- u8 - channels (1-first, 2-second, 3-both)
+
+### WAVE_SAWTOOTH_DOWN (4)
+Start a falling sawtooth
+
+*Request:*
+- u8 - channels (1-first, 2-second, 3-both)
+
+### WAVE_RECTANGLE (5)
+Start a rectangle waveform (pulse train)
+
+*Request:*
+- u8 - channels (1-first, 2-second, 3-both)
+- u16 - ontime in DDS table length (presently 0-8191)
+- u16 - high level 0-4095
+- u16 - low level 0-4095
+
+### SYNC (10)
+Synchronize the two channels (set phase = 0)
+
+### SET_FREQUENCY (20)
+Set the frequency
+
+*Request:*
+- u8 - channels (1-first, 2-second, 3-both)
+- float32 - frequency (Hz)
+
+### SET_PHASE (21)
+Set a channel's phase, relative to the initial synchronized phase.
+It's recommended to set phase only of one channel, leaving the other at 0°.
+
+*Request:*
+- u8 - channels (1-first, 2-second, 3-both)
+- u16 - phase in DDS table length (presently 0-8191)
+
+### SET_DITHER (22)
+Set dithering mode and strength
+
+*Request:*
+- u8 - channels (1-first, 2-second, 3-both)
+- u8 - noise type (0-none, 1-white, 2-triangle)
+- u8 - number of noise bits
+
+Please note that setting high number of noise bits can lead to overflow/underflow
+(probably a STM32 bug).
+
+## Events
+
+*No events defined for this unit type.*