Add HelpSource for ZZZ, ZZZDevice and ZZZError

Add schelp files for ZZZ, ZZZDevice and ZZZError, explaining (mostly
all) class and instance methods and giving code examples.

1 files changed, 289 insertions, 0 deletions

diff --git a/HelpSource/Classes/ZZZDevice.schelp b/HelpSource/Classes/ZZZDevice.schelp
new file mode 100644
index 0000000..b23b2c3
--- /dev/null
+++ b/HelpSource/Classes/ZZZDevice.schelp
@@ -0,0 +1,289 @@
+TITLE:: ZZZDevice
+summary:: Interface Expert Sleepers devices
+categories:: External Control>Eurorack
+related:: Classes/ZZZ, Reference/ZZZ
+
+DESCRIPTION::
+This class provides an interface to Expert Sleepers' Eurorack modules.
+It offers convenience methods to create clocks and gates on the device's
+outputs, based on (shared) link::Classes/TempoBusClock##TempoBusClocks::.
+
+note:: ZZZDevice assumes that the (ADAT) channels used to interface with the Eurorack module are set to 0.0dB at +4dBu.::
+
+CLASSMETHODS::
+
+METHOD:: new
+Creates an instance of ZZZDevice on a link::Classes/Server:: using an
+link::Classes/Array:: of output bus channels (within the range of
+link::Classes/ServerOptions#-numOutputBusChannels::).
+Throws link::Classes/ZZZError:: if the parameters ar not set or invalid.
+
+ARGUMENT:: channels
+An link::Classes/Array:: of link::Classes/Integer##Integers::, that represent
+output bus channels indeces (within the range of
+link::Classes/ServerOptions#-numOutputBusChannels::) on the
+link::Classes/Server:: instance.
+
+ARGUMENT:: server
+The link::Classes/Server:: instance to use.
+
+returns:: An instance of ZZZDevice interfacing the given hardware device.
+
+METHOD:: playTypes
+Return the understood playTypes that can be used. A code::playType:: relates to
+how scheduling takes place on a given link::Classes/TempoBusClock:: when adding
+or changing clocks on an output:
+
+list::
+## code::\beat::: When this code::playType:: is used the clock is added/ changed/ removed on the next beat.
+## code::\bar::: When this code::playType:: is used the clock is added/ changed/ removed on the next bar.
+::
+
+returns:: An link::Classes/Array:: of link::Classes/Symbol##Symbols:: 
+representing the understood code::playTypes::.
+
+METHOD:: clockTypes
+Return the understood types of clocks that can be used:
+
+list::
+## code::\zeroFive::: A clock signal ranging from code::0.0:: to code::5.0:: (24 beats per qarter note)
+## code::\minusFiveFive::: A clock signal ranging from code::-5.0:: to code::5.0:: (24 beats per qarter note)
+## code::\korgZeroFive::: A clock signal ranging from code::0.0:: to code::5.0:: (48 beats per quarter note)
+## code::\korgMinusFiveFive::: A clock signal ranging from code::-5.0:: to code::5.0:: (48 beats per quarter note)
+::
+
+returns:: An link::Classes/Array:: of link::Classes/Symbol##Symbols:: 
+representing the understood code::clockTypes::.
+
+
+INSTANCEMETHODS::
+
+subsection::Initialization
+
+METHOD:: init
+Initializes the link::Classes/Dictionary##Dictionaries:: required for
+link::#-clocks::, link::#-gates::, link::#-gateBusses::, link::#-outs::,
+link::#-tempos:: and link::#-tempoBusses::, as well as populates the
+link::#-outs:: link::Classes/Dictionary:: and initializes link::#-deviceGroup:: 
+when the link::Classes/Server:: is booted.
+
+note::This method is called when creating a new instance of ZZZDevice using link::#*new::.::
+
+subsection::Adding and Removing
+
+METHOD:: addTempo
+Adds a link::Classes/TempoBusClock:: to the link::#-tempos:: link::Classes/Dictionary::. Throws link::Classes/ZZZError:: on invalid input.
+
+ARGUMENT:: slot
+An link::Classes/Integer:: (code::>=1::) identifying the slot to use for the link::Classes/TempoBusClock::.
+
+ARGUMENT:: tempo
+A link::Classes/Float:: (code::>=0.0::) setting the tempo.
+
+METHOD:: removeTempo
+Removes a link::Classes/TempoBusClock:: from the link::#-tempos:: link::Classes/Dictionary:: and any clock relying on it.
+
+ARGUMENT:: slot
+An link::Classes/Integer:: (code::>=1::) identifying the link::Classes/TempoBusClock:: in the link::#-tempos:: link::Classes/Dictionary::.
+
+ARGUMENT:: playType
+A link::Classes/Symbol:: describing the code::playType:: to use (see link::#*playTypes:: for the valid types and explanation).
+
+ARGUMENT:: quant
+An link::Classes/Integer:: setting the quant (the beat) on which to schedule removal of the tempo and clock link::Classes/Synth##Synth(s)::.
+Only regarded if code::playType:: is set to code::\beat::.
+
+METHOD:: addClock
+Adds a clock link::Classes/Synth:: on a hardware output. Throws
+link::Classes/ZZZError:: on invalid input.
+
+note::Requires a tempo to be setup beforehand (see link::#-addTempo::).::
+
+ARGUMENT:: output
+An link::Classes/Integer:: (code::>=1::) identifying the code::output:: on a hardware device.
+
+ARGUMENT:: slot
+An link::Classes/Integer:: (code::>=1::) identifying the tempo slot to use for the clock (see link::#-addTempo:: on how to add a tempo).
+
+ARGUMENT:: type
+A link::Classes/Symbol:: describing the clock type to use (see link::#*clockTypes:: for the valid types and explanation).
+
+ARGUMENT:: playType
+A link::Classes/Symbol:: describing the code::playType:: to use (see link::#*playTypes:: for the valid types and explanation).
+
+ARGUMENT:: quant
+An link::Classes/Integer:: setting the quant (the beat) on which to schedule playing the clock link::Classes/Synth::.
+Only regarded if code::playType:: is set to code::\beat::.
+
+ARGUMENT:: replace
+A link::Classes/Boolean:: indicating whether to replace clock currently playing at code::output::.
+
+METHOD:: removeClock
+Removes a clock link::Classes/Synth:: playing on a hardware output.
+Throws link::Classes/ZZZError:: on invalid input.
+
+ARGUMENT:: output
+An link::Classes/Integer:: (code::>=1::) identifying the code::output:: on a hardware device.
+
+ARGUMENT:: playType
+A link::Classes/Symbol:: describing the code::playType:: to use (see link::#*playTypes:: for the valid types and explanation).
+
+ARGUMENT:: quant
+An link::Classes/Integer:: setting the quant (the beat) on which to schedule removal of the clock link::Classes/Synth::.
+Only regarded if code::playType:: is set to code::\beat::.
+
+METHOD:: addGate
+Adds a gate link::Classes/Synth:: on a hardware output. Throws link::Classes/ZZZError:: on invalid input.
+The gate's multiplication value can be controlled using the respective link::Classes/Bus:: exposed in link::#-gateBusses::.
+
+ARGUMENT:: output
+An link::Classes/Integer:: (code::>=1::) identifying the code::output:: on a hardware device.
+
+ARGUMENT:: input
+A link::Classes/Float:: (code::>=0.0, <=1.0::) setting the initial multiplication value.
+
+METHOD:: removeGate
+Removes a gate link::Classes/Synth:: from a hardware output. Throws link::Classes/ZZZError:: on invalid input.
+
+ARGUMENT:: output
+An link::Classes/Integer:: (code::>=1::) identifying the code::output:: on ahardware device.
+
+subsection::Setting Data
+
+METHOD:: setClockTempo
+Sets the link::Classes/TempoBusClock:: used for a given clock on an code::output:: of an Expert Sleepers device. Throws link::Classes/ZZZError:: on invalid input.
+
+ARGUMENT:: output
+An link::Classes/Integer:: (code::>=1::) identifying the code::output:: on ahardware device.
+
+ARGUMENT:: slot
+An link::Classes/Integer:: (code::>=1::) identifying the link::Classes/TempoBusClock:: in the link::#-tempos:: link::Classes/Dictionary::.
+
+ARGUMENT:: playType
+A link::Classes/Symbol:: describing the code::playType:: to use (see link::#*playTypes:: for the valid types and explanation).
+
+ARGUMENT:: quant
+An link::Classes/Integer:: setting the quant (the beat) on which to schedule playing the clock link::Classes/Synth::.
+Only regarded if code::playType:: is set to code::\beat::.
+
+ARGUMENT:: type
+A link::Classes/Symbol:: describing the clock type to use (see link::#*clockTypes:: for the valid types and explanation).
+
+METHOD:: setTempo
+Sets the tempo of a link::Classes/TempoBusClock:: (see link::#-addTempo:: on how to add a tempo).
+
+note::It may prove more pragmatic to write to the tempo's respective link::Classes/Bus:: in link::#-tempoBusses::.::
+
+ARGUMENT:: slot
+An link::Classes/Integer:: (code::>=1::) identifying the link::Classes/TempoBusClock:: in the link::#-tempos:: link::Classes/Dictionary::.
+
+ARGUMENT:: tempo
+A link::Classes/Float:: (code::>=0.0::) setting the tempo.
+
+subsection::Accessing Data
+
+METHOD:: clocks
+Returns a link::Classes/Dictionary:: of hardware output numbers and their
+respective clock link::Classes/Synth##Synths:: (see link::#-addClock:: on how to add a clock).
+
+returns:: A link::Classes/Dictionary:: of link::Classes/Integer:: and link::Classes/Synth:: associations.
+
+METHOD:: deviceGroup
+Returns the link::Classes/Group:: instance to which all link::Classes/Synth##Synths:: are added.
+This variable is setup during link::#-init::.
+
+returns:: A link::Classes/Group::.
+
+METHOD:: gateBusses
+Returns a link::Classes/Dictionary:: of hardware outputs and their respective
+link::Classes/Bus##Busses:: connected to the gate
+link::Classes/Synth##Synths:: (see link::#-addGate:: on how to setup a gate).
+
+returns:: A link::Classes/Dictionary:: of link::Classes/Integer:: and link::Classes/Bus:: associations.
+
+METHOD:: gates
+Returns a link::Classes/Dictionary:: of hardware output numbers and their
+respective gate link::Classes/Synth##Synths:: (see link::#-addGate:: on how to
+add a gate).
+
+returns:: A link::Classes/Dictionary:: of link::Classes/Integer:: and link::Classes/Synth:: associations.
+
+METHOD:: outs
+Returns a link::Classes/Dictionary:: representing the mapping between the outputs
+on the hardware (the numbering starts at code::1::) and the
+link::Classes/Server::'s output bus channels (within the range of
+link::Classes/ServerOptions#-numOutputBusChannels::) connected to the hardware.
+
+returns:: A link::Classes/Dictionary:: of link::Classes/Integer:: associations.
+
+METHOD:: outputOnHardware
+Returns the output bus channel (an link::Classes/Integer:: within the range of
+link::Classes/ServerOptions#-numOutputBusChannels::) mapped to a given hardware
+output number.
+Throws link::Classes/ZZZError:: if the output parameter is invalid.
+
+ARGUMENT:: output
+An link::Classes/Integer:: (code::>=1::) identifying the code::output:: on a hardware device.
+
+returns:: An link::Classes/Integer:: representing an output bus channel.
+
+METHOD:: tempoBusses
+Returns a link::Classes/Dictionary:: of slots (starting from code::1::) and
+their respective link::Classes/Bus##Busses::, which are connected to
+link::Classes/TempoBusClock##TempoBusClocks:: and clock link::Classes/Synth##Synths::.
+
+returns:: A link::Classes/Dictionary:: of link::Classes/Integer:: and link::Classes/Bus:: associations.
+
+METHOD:: tempos
+Returns a link::Classes/Dictionary:: of the currently available tempos (see
+link::#-addTempo:: on how to setup a tempo).
+
+returns:: A link::Classes/Dictionary:: of slots (link::Classes/Integer::) and link::Classes/TempoBusClock:: associations.
+
+subsection::Posting Information
+
+METHOD:: postAll
+Convenience wrapper around link::#-postClocks::, link::#-postGates::, link::#-postOuts:: and link::#-postTempos::.
+
+METHOD:: postClocks
+Posts information about the currently running clocks.
+
+METHOD:: postGates
+Posts information about the currently running gate link::Classes/Synth##Synth(s)::.
+
+METHOD:: postOuts
+Posts information about the mapping of hardware outputs to link::Classes/Server:: output bus channels.
+
+METHOD:: postTempos
+Posts information about the currently running link::Classes/TempoBusClock##TempoBusClocks::.
+
+EXAMPLES::
+
+code::
+// first Server output bus channel of ADAT connection to Expert Sleepers hardware device
+// this might be different depending on hardware or sclang startup configuration
+~firstChannel = 12;
+
+// initialize connection
+s.waitForBoot(
+  ~zzzdevice = ZZZDevice.new(server: s, channels: Array.series(8, start: ~firstChannel, step: 1));
+);
+
+// add a tempo
+~zzzdevice.addTempo(slot: 1, tempo: 120/60);
+
+// add a clock on the first hardware output using the above tempo
+~zzzdevice.addClock(output: 1, slot: 1);
+
+// add a gate on the second hardware output
+~zzzdevice.addGate(output: 6);
+
+// set the tempo
+~zzzdevice.setTempo(slot: 1, tempo: 180/60);
+
+// remove everything
+(
+  ~zzzdevice.removeTempo(slot: 1);
+  ~zzzdevice.removeGate(output: 6);
+)
+::