ioio.lib.api
Class Sequencer.ChannelCueSteps

java.lang.Object
  ioio.lib.api.Sequencer.ChannelCueSteps

All Implemented Interfaces:

Sequencer.ChannelCue

Enclosing interface:

Sequencer

public static class Sequencer.ChannelCueSteps
extends java.lang.Object
implements Sequencer.ChannelCue

A cue for a steps channel.

Determines the clock rate, pulse width and period durations while this cue is executing. This kind of channel produces deterministic waveforms, which are typically used to generate a precise number of steps during a given cue period. However, this comes at a cost of being a little more involved from the user's perspective, since delicate timing considerations need to be taken into account.

The number of steps within a given cue period is given by floor(Tc / Ts), where Tc is the cue duration and Ts is the step period duration. Each pulse is center-aligned within its period. In order to maintain a deterministic result, the user must guarantee that no pulse falls within the last 6 microseconds of the cue period (this effectively limits the maximum pulse rate to 80[kHz], considering the the pulse itself must be at least 1/8[us] wide, and that the rising edge of the pulse is center-aligned). Thus, it is possible that due to precision limitations, in an arbitrarily long period it will be impossible to generate the exact number of desired pulses. Likewise, a very low pulse rate (high pulse duration) may be outside of the permitted range or will result in having to use a slower time-base. The solution to both problems is splitting a single cue into two or more cues of shorted durations, until eventually the precision is sufficient (this always converges, since eventually we can always go to arbitrarily short cue durations, so that each one contains either zero or one steps.

A steps channel allows determining the clock rate on a per-cue basis. This often allows avoiding having to split cues, thus resulting in a less total cues and more efficient execution. The rule for choosing the correct clock is to always use the highest rate that will cause the resulting period to be <= 2^16. In other words, choose the highest available clock which is less than or equal to (2^16 / Tp) or (2^16 * Fp), where Tp is the desired period in seconds, or Fp is the desired frequency in Hz. For example, if we want to generate pulses at 51Hz, 65536 * Fp = 3.34MHz, so we should use the 2MHz clock, and the period value will be round(2MHz / 51Hz) = 39216. This result in an actual rate of 2MHz / 39216 ~= 50.9996[Hz].

Field Summary

Sequencer.Clock	clk The clock rate for this cue.
int	period The pulse period, in time-base units, as determined for this channel in its configuration.
int	pulseWidth The pulse-width, in time-base units, as determined for this channel in its configuration.

Constructor Summary

Sequencer.ChannelCueSteps()

Method Summary

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

clk

public Sequencer.Clock clk

The clock rate for this cue. See discussion in the class documentation on how to choose it.

pulseWidth

public int pulseWidth

The pulse-width, in time-base units, as determined for this channel in its configuration. Valid values are [0..floor(period / 2)].

period

public int period

The pulse period, in time-base units, as determined for this channel in its configuration. Valid values are [3..65536].

Constructor Detail

Sequencer.ChannelCueSteps

public Sequencer.ChannelCueSteps()