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);
)
::