Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reorganize docs sections and split cheatsheet in two #333

Merged
merged 12 commits into from
Dec 19, 2023
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -53,5 +53,5 @@ __pycache__/
/docs/teletype.pdf
/docs/teletype.html
/docs/cheatsheet/*
!/docs/cheatsheet/cheatsheet.tex
!/docs/cheatsheet/cs-common.tex
/docs/testServe/
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
- **NEW**: apply VCV Rack compatibility patches, so branches off main can be used in both hardware and software
- **FIX**: update Disting EX looper ops to work with Disting EX firmware 1.23+
- **NEW**: new dual W/ ops: `W/.SEL`, `W/S.POLY`, `W/S.POLY.RESET`, `W/1`, `W/2`
- **NEW**: split cheatsheets into separate PDFs for core ops and i2c

## v4.0.0

Expand Down
15 changes: 9 additions & 6 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
.PHONY: build clean

build: teletype.pdf teletype.html cheatsheet/cheatsheet.pdf
build: teletype.pdf teletype.html cheatsheet/cheatsheet.pdf cheatsheet/cheatsheet-i2c.pdf

clean:
rm -f teletype.pdf && \
rm -f teletype.html && \
rm -f cheatsheet/include.tex && \
rm -f cheatsheet/cheatsheet-*.* && \
cd cheatsheet && \
latexmk -xelatex -c && \
rm -f cheatsheet.pdf
Expand All @@ -18,8 +18,11 @@ teletype.html: $(wildcard *.md ops/*.md ops/*.toml) \
../utils/docs.py ../CHANGELOG.md $(wildcard ../utils/templates/*)
../utils/docs.py teletype.html

cheatsheet/include.tex: $(wildcard ops/*.toml) ../utils/cheatsheet.py
../utils/cheatsheet.py "cheatsheet/include.tex"
cheatsheet/cheatsheet-%.tex: $(wildcard ops/*.toml) ../utils/cheatsheet.py
../utils/cheatsheet.py $* "cheatsheet/cheatsheet-$*.tex"

cheatsheet/cheatsheet.pdf: cheatsheet/cheatsheet.tex cheatsheet/include.tex
cd cheatsheet && latexmk -xelatex cheatsheet.tex
cheatsheet/cheatsheet-%.pdf: cheatsheet/cs-common.tex cheatsheet/cheatsheet-%.tex
cd cheatsheet && latexmk -xelatex cs-common.tex -jobname=cheatsheet-$*

cheatsheet/cheatsheet.pdf: cheatsheet/cheatsheet-core.pdf
cd cheatsheet && cp cheatsheet-core.pdf cheatsheet.pdf
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@
\begin{document}

\begin{multicols}{5}
\input{include.tex}
\input{\jobname.tex}

%% add a page break at the end to force the last column to not balance
\pagebreak
Expand Down
1 change: 1 addition & 0 deletions docs/ops/calibration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
## Calibration
93 changes: 93 additions & 0 deletions docs/ops/calibration.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@

["DEVICE.FLIP"]
prototype = "DEVICE.FLIP"
short = "Flip the screen/inputs/outputs"
description = """
Flip the screen, the inputs and the outputs. This op is useful if you want to mount your Teletype upside down.
The new state will be saved to flash.
"""

["IN.CAL.MIN"]
prototype = "IN.CAL.MIN"
short = "Reads the input CV and assigns the voltage to the zero point"
description = """
1. Connect a patch cable from a calibrated voltage source
2. Set the voltage source to 0 volts
3. Execute IN.CAL.MIN from the live terminal
4. Call IN and confirm the 0 result
"""

["IN.CAL.MAX"]
prototype = "IN.CAL.MAX"
short = "Reads the input CV and assigns the voltage to the max point"
description = """
5. Set the voltage source to target maximum voltage (10V)
6. Execute IN.CAL.MAX from the live terminal
7. Call IN and confirm that the result is 16383
"""

["IN.CAL.RESET"]
prototype = "IN.CAL.RESET"
short = "Resets the input CV calibration"

["PARAM.CAL.MIN"]
prototype = "PARAM.CAL.MIN"
short = "Reads the Parameter Knob minimum position and assigns a zero value"
description = """
1. Turn the PARAM knob all the way to the left
2. Execute PARAM.CAL.MIN from the live terminal
3. Call PARAM and confirm the 0 result
"""

["PARAM.CAL.MAX"]
prototype = "PARAM.CAL.MAX"
short = "Reads the Parameter Knob maximum position and assigns the maximum point"
description = """
4. Turn the knob all the way to the right
5. Execute PARAM.CAL.MAX from the live terminal
6. Call PARAM and verify that the result is 16383
"""

["PARAM.CAL.RESET"]
prototype = "PARAM.CAL.RESET"
short = "Resets the Parameter Knob calibration"

["CV.CAL"]
prototype = "CV.CAL n mv1v mv3v"
short = "Calibrate CV output `n`"
description = """
Following a short calibration procedure, you can use `CV.CAL` to more
precisely match your CV outputs to each other or to an external reference. A
digital multimeter (or other voltage measuring device) is required.

To calibrate CV 1, first set it to output one volt with `CV 1 V 1`. Using
a digital multimeter with at least millivolt precision (three digits after
the decimal point), record the measured output of CV 1 between tip and sleeve
on a patch cable. Then set CV 1 to three volts with `CV 1 V 3` and measure
again.

Once you have both measurements, use the observed 1V and 3V values in
millivolts as the second and third arguments to `CV.CAL`. For example, if you
measured 0.990V and 2.984V, enter `CV.CAL 1 990 2984`. (If both your
measurements are within 1 or 2 millivolts already, there's no need to run
`CV.CAL`.)

Measure the output with `CV 1 V 1` and `CV 1 V 3` again and confirm the values
are closer to the expected 1.000V and 3.000V.

Repeat the above steps for CV 2-4, if desired. The calibration data is stored
in flash memory so you only need to go through this process once.

Note: The calibration adjustment is made after `CV.SLEW` and `CV.OFF` are
applied, and does not affect `CV.GET` or any other scene-visible values. It
only affects the levels coming out of the DAC.
"""

["CV.CAL.RESET"]
prototype = "CV.CAL.RESET n"
short = "Reset calibration data for CV output `n`"
description = """
Clear the calibration data for CV output `n` and return it to its default
behavior, with no calibration adjustment.
"""

4 changes: 2 additions & 2 deletions docs/ops/controlflow.toml
Original file line number Diff line number Diff line change
Expand Up @@ -398,7 +398,7 @@ Does not affect the CV input (IN) or the Parameter knob (PARAM) values.

["INIT.P"]
prototype = "INIT.P x"
short = "clears pattern associated with pattern number x"
short = "clears pattern number x"

["INIT.P.ALL"]
prototype = "INIT.P.ALL"
Expand All @@ -422,7 +422,7 @@ short = "clear time on trigger x"

["INIT.TR"]
prototype = "INIT.TR x"
short = "clear all parameters on trigger associated with TR x"
short = "clear all parameters on trigger x"

["INIT.TR.ALL"]
prototype = "INIT.TR.ALL"
Expand Down
124 changes: 20 additions & 104 deletions docs/ops/hardware.toml
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@ output `x` to `y`.
"""

["CV.SET"]
prototype = "CV.SET x"
short = "Set CV value"
prototype = "CV.SET x y"
short = "Set CV value, ignoring slew"
description = """
Set the CV value at output `x` bypassing any slew settings.
"""
Expand All @@ -40,44 +40,13 @@ Get the slew time in ms associated with CV output `x`. Set the slew time
associated with CV output `x` to `y` ms.
"""

["CV.CAL"]
prototype = "CV.CAL n mv1v mv3v"
short = "Calibrate CV output `n`"
description = """
Following a short calibration procedure, you can use `CV.CAL` to more
precisely match your CV outputs to each other or to an external reference. A
digital multimeter (or other voltage measuring device) is required.

To calibrate CV 1, first set it to output one volt with `CV 1 V 1`. Using
a digital multimeter with at least millivolt precision (three digits after
the decimal point), record the measured output of CV 1 between tip and sleeve
on a patch cable. Then set CV 1 to three volts with `CV 1 V 3` and measure
again.

Once you have both measurements, use the observed 1V and 3V values in
millivolts as the second and third arguments to `CV.CAL`. For example, if you
measured 0.990V and 2.984V, enter `CV.CAL 1 990 2984`. (If both your
measurements are within 1 or 2 millivolts already, there's no need to run
`CV.CAL`.)

Measure the output with `CV 1 V 1` and `CV 1 V 3` again and confirm the values
are closer to the expected 1.000V and 3.000V.
[V]
prototype = "V x"
short = "converts a voltage to a value usable by the CV outputs (`x` between `0` and `10`)"

Repeat the above steps for CV 2-4, if desired. The calibration data is stored
in flash memory so you only need to go through this process once.

Note: The calibration adjustment is made after `CV.SLEW` and `CV.OFF` are
applied, and does not affect `CV.GET` or any other scene-visible values. It
only affects the levels coming out of the DAC.
"""

["CV.CAL.RESET"]
prototype = "CV.CAL.RESET n"
short = "Reset calibration data for CV output `n`"
description = """
Clear the calibration data for CV output `n` and return it to its default
behavior, with no calibration adjustment.
"""
[VV]
prototype = "VV x"
short = "converts a voltage to a value usable by the CV outputs (`x` between `0` and `1000`, `100` represents 1V)"

["IN"]
prototype = "IN"
Expand All @@ -102,51 +71,6 @@ Get the value of the PARAM knob. This returns a valuue in the range 0-16383.
prototype = "PARAM.SCALE min max"
short = "Set static scaling of the PARAM knob to between `min` and `max`."

["IN.CAL.MIN"]
prototype = "IN.CAL.MIN"
short = "Reads the input CV and assigns the voltage to the zero point"
description = """
1. Connect a patch cable from a calibrated voltage source
2. Set the voltage source to 0 volts
3. Execute IN.CAL.MIN from the live terminal
4. Call IN and confirm the 0 result
"""

["IN.CAL.MAX"]
prototype = "IN.CAL.MAX"
short = "Reads the input CV and assigns the voltage to the max point"
description = """
5. Set the voltage source to target maximum voltage (10V)
6. Execute IN.CAL.MAX from the live terminal
7. Call IN and confirm that the result is 16383
"""

["IN.CAL.RESET"]
prototype = "IN.CAL.RESET"
short = "Resets the input CV calibration"

["PARAM.CAL.MIN"]
prototype = "PARAM.CAL.MIN"
short = "Reads the Parameter Knob minimum position and assigns a zero value"
description = """
1. Turn the PARAM knob all the way to the left
2. Execute PARAM.CAL.MIN from the live terminal
3. Call PARAM and confirm the 0 result
"""

["PARAM.CAL.MAX"]
prototype = "PARAM.CAL.MAX"
short = "Reads the Parameter Knob maximum position and assigns the maximum point"
description = """
4. Turn the knob all the way to the right
5. Execute PARAM.CAL.MAX from the live terminal
6. Call PARAM and verify that the result is 16383
"""

["PARAM.CAL.RESET"]
prototype = "PARAM.CAL.RESET"
short = "Resets the Parameter Knob calibration"

["TR"]
prototype = "TR x"
prototype_set = "TR x y"
Expand All @@ -156,14 +80,12 @@ Get the current state of trigger output `x`. Set the state of trigger
output `x` to `y` (0-1).
"""

["TR.POL"]
prototype = "TR.POL x"
prototype_set = "TR.POL x y"
short = "Set polarity of trigger output x to y (0-1)"
["TR.PULSE"]
prototype = "TR.PULSE x"
aliases = ["TR.P"]
short = "Pulse trigger output x"
description = """
Get the current polarity of trigger output `x`. Set the polarity of trigger
output `x` to `y` (0-1). When TR.POL = 1, the pulse is 0 to 1 then back to 0.
When TR.POL = 0, the inverse is true, 1 to 0 to 1.
Pulse trigger output x.
"""

["TR.TIME"]
Expand All @@ -182,12 +104,14 @@ description = """
Flip the state of trigger output `x`.
"""

["TR.PULSE"]
prototype = "TR.PULSE x"
aliases = ["TR.P"]
short = "Pulse trigger output x"
["TR.POL"]
prototype = "TR.POL x"
prototype_set = "TR.POL x y"
short = "Set polarity of trigger output x to y (0-1)"
description = """
Pulse trigger output x.
Get the current polarity of trigger output `x`. Set the polarity of trigger
output `x` to `y` (0-1). When TR.POL = 1, the pulse is 0 to 1 then back to 0.
When TR.POL = 0, the inverse is true, 1 to 0 to 1.
"""

["MUTE"]
Expand All @@ -205,14 +129,6 @@ description = """
Read the current state of trigger input `x` (0=low, 1=high).
"""

["DEVICE.FLIP"]
prototype = "DEVICE.FLIP"
short = "Flip the screen/inputs/outputs"
description = """
Flip the screen, the inputs and the outputs. This op is useful if you want to mount your Teletype upside down.
The new state will be saved to flash.
"""

["LIVE.OFF"]
prototype = "LIVE.OFF"
aliases = ["LIVE.O"]
Expand Down
4 changes: 2 additions & 2 deletions docs/ops/i2c2midi.toml
Original file line number Diff line number Diff line change
Expand Up @@ -418,15 +418,15 @@ Set strumming of chord `x` (0..8) to `x` ms (0..32767). Strumming plays the note

["I2M.C.VCUR"]
prototype = "I2M.C.VCUR w x y z"
alias = ["I2M.C.V~"]
aliases = ["I2M.C.V~"]
short = "Set velocity curve for chord `w` (0..8) with curve type `x` (0..5), start value `y`% (0..32767) and end value `z`% (0..32767), use `w = 0` to set for all chords, use `x = 0` to turn off"
description = """
Set velocity curve for chord `w` (0..8) with curve type `x` (0..5), start value `y`% (0..32767) and end value `z`% (0..32767). This will affect the velocity of the notes in the order they are defined in the chord. Start and end percentages refer to the velocity with which the chord is played via `I2M.C`. Use `x = 0` to turn velocity curve off. The following curves are available: 0) Off 1) Linear 2) Exponential 3) Triangle 4) Square 5) Random. Use `w = 0` to set velocity curve for all chords. Try a random curve with subtle values for a humanizing effect.
"""

["I2M.C.TCUR"]
prototype = "I2M.C.TCUR w x y z"
alias = ["I2M.C.T~"]
aliases = ["I2M.C.T~"]
short = "Set time curve to strumming for chord `w` (0..8) with curve type `x` (0..5), start value `y`% (0..32767) and end value `z`% (0..32767), use `w = 0` to set for all chords, use `x = 0` to turn off"
description = """
Set time curve for chord `w` (0..8) with curve type `x` (0..5), start value `y`% (0..32767) and end value `z`% (0..32767). This will affect the time interval between the notes in the order they are defined in the chord. Start and end percentages refer to the current strumming setting of the chord, set via `I2M.C.STR`. Use `x = 0` to turn time curve off. The following curves are available: 0) Off 1) Linear 2) Exponential 3) Triangle 4) Square 5) Random. Use `w = 0` to set time curve for all chords. Try a square curve with similar values to create swing. Try a random curve with subtle values for a humanizing effect.
Expand Down
Loading
Loading