The Morsel plays sequences like a media player plays music or video, except that these produce not sound or pictures but light to LED’s. But what is a sequence?
A sequence is a list of statements that happen in order. Statement types include time stamps, setting of brightness, and Go.
Time Stamps
A time stamp is a moment of time that the player must match to move on to the next statement. There are two types of time stamps: absolute and relative.
Absolute Time Stamps
Absolute time stamps begin with the At sign (@) followed by a time. In the example below, the “Joe’s” line would read, “At two seconds, Channel 3 equals 100 percent brightness”.
//Eat At Joe's
//Diner progressive sign in 1 second steps
//using 3 LED's
@0s Chn1 = 100% //Eat...
@1s Chn2 = 100% //At...
@2s Chn3 = 100% //Joe's!
//All stay on for 2 seconds
@4s Chn1 = 0% //All turn off at same time
Chn2 = 0%
Chn3 = 0%
//All stay off for 1 second
@5s //wait until 5 seconds to end and start over
The zero second time stamp (@Os) is actually redundant, since the player begins the sequence at 0 seconds. That time stamp was provided to clarify to the reader when channel 1 turns on.
Absolute time stamps make it easy to see the total elapsed time. This sequence repeats every 5 seconds.
Comments begin with double slashes (//). They and anything that follows to the end of the line is removed by Sequence Composer before exporting the sequence to the Morsel. Comments are purely for humans to document what the code does.
Relative Time Stamps
Relative time stamps add their value to the time immediately before it. The above sequence could have been written in this form:
//Eat At Joe's
//in relative time
@+0s Chn1 = 100% //Eat...
@+1s Chn2 = 100% //At...
@+1s Chn3 = 100% //Joe's!
//All stay on for 2 seconds
@+2s Chn1 = 0% //All turn off at same time
Chn2 = 0%
Chn3 = 0%
//All stay off for 1 second
@+1s //Wait one more second, then start over
The Joe’s line would read, “At plus 1 second, channel 3 equals 100 percent brightness.”
Relative time stamps make it easy to see the time between neighboring lines of the sequence. They also have the advantage that they can be copied and pasted again and again without the need to change any time stamps.
A mixture of relative and absolute time stamps is sometimes convenient. We might lose track of how we are adding and removing lines of code, but we always want the total to be 5 seconds. We could change the last line:
//Eat At Joe's
//Relative mixed with absolute time
@+0s Chn1 = 100% //Eat...
@+1s Chn2 = 100% //At...
@+1s Chn3 = 100% //Joe's!
//All stay on for 2 seconds
@+2s Chn1 = 0% //All turn off at same time
Chn2 = 0%
Chn3 = 0% //All stay off for 1 second
@5s //wait until 5 seconds and start over
If the relative time stamps had added up to more than 5 seconds when the player reached the “@5s” line, then the player would pass through it immediately. Reaching the end of the sequence, it would start over.
Ending in 0 or 5ms
Sequence Composer accepts time stamps in seconds or milliseconds, where 1.005s = 1005ms. Single milliseconds are too fast to be discerned by the eye, so the Morsel divides time into 5ms time slices. If a time stamp ends in a digit other than 0 or 5 milliseconds, it will be rounded down. It is best to stick with the Morsel’s time base to keep clearly visible what is happening and when.
Even 5ms is often too fast. A video camera may not see a flash if it is shorter than 35ms. This should be kept in mind when creating camera-ready sequences.
Brightness
There are three kinds of brightness statements: Constant, Fade From and Fade To. Fades are covered in anohl. The constant statement was already seen above:
chn3 = 33% //set to 1/3 brightness
Brightness is given in percent, 0 to 100%. The optional percent sign adds to readability. Fractional percentages are allowed as long as a number precedes the decimal point (use 0.5%, not .5%). Half percents are reliably depicted, but finer fractions sometimes round off to the same brightness. For programmers, brightness may also be given in the following notation: 0x00 through 0xff.
Go Statements
There are three types of Go statements: Go to label, Go between label1 and label2, and Go to label with chance.
The first two will always go but the third, Go to label with chance, has a random probability and may not occur. If it does not, the player continues to the next statement. In all other cases, the Go statement does two things:
- It moves the player’s position to the label
- It resets the player’s time to the time stamp of the label
It then begins executing statements that follow the label. The sequence below has an initial warmup followed by a perpetual loop. The Go To keeps the warmup from being repeated:
// Warmup section
@0s chn1 = 10% //brighten gradually
@+1s chn1 = 25%
@+1s chn1 = 50%
@+1s chn1 = 100%
// Falls through after "warmup"
// Continuous running section, blinks on & off
// Time stamp of the following label is 3 seconds
blinkLoop //the label
@+1s //wait 1 second, then...
chn1 = 0% //turn off
@+0.5s //wait 1/2 second, then...
chn1 = 100% //turn on
go to blinkLoop //repeat continuously
Additional details on Go statements are covered in another tutorial.
Details
Excesses
Untimed loops are too fast to see. A sequence with such a loop is soon halted by the Morsel because it hogs the CPU. They occur when a Go statement loops back to a label within the same time stamp. Make the label at least 5ms earlier than the Go.
Out of order time stamps should be avoided. That is because any lower numbered time stamps that follow will be executed immediately. If too many statements occur in the same time tick (more than 250), the sequence will be halted by the Morsel.
Memory
Sequences can be any length up to available memory, which holds thousands of lines of custom code.
Any number of time stamps may be added to a file. They will not consume more memory in the Morsel
The size of the sequence and available memory are reported on the Export window after connecting a Morsel to the ComLink. More space may be freed by replacing large custom sequences with empty ones.
Duration
The maximum time stamp is just over 5 minutes, 27 seconds, at 327.675 seconds or 327675ms. Later, we’ll see a way to go beyond that.
Time stamps may contain decimal points but must begin with a digit (0.5s is okay but .5s is not).
Conclusion
This introduction hits the newcomer with a lot of information. If you’re starting to get the hang of it, that is a very good sign indeed, because it doesn’t take much more to begin writing some really interesting sequences. A Fade here, a Go there, pretty soon you’re talking real effects.