Hi Eric:
Sorry about that - our example projects are sometimes a bit ahead of what we have described in the reference section. This happens when we want to get a particular example out in the world so that people can use it, even if it contains commands that aren't documented yet. We do make an attempt to document the code really well so that users can understand the commands anyway. We're happy to see that you're investigating the code closely enough to suss this out!
As mentioned in the Hardware pages, the P3 pins can be used as PWM outputs, and these can be used to drive LEDs or motors or anything else you want to control with PWM. This comes in handy for varying the brightness of LEDs and controlling the speed of a motor. Our "LED Fade" example program shows the basics for how to use the PWM output pins. In order to use a pin for PWM you need to enable that function using the "pwmio_en" command. For example pwmio_en1 will enable PWM on the P3.0 pin. Similarly, the "pwmio_dis" command is used to disable the PWM function on a particular pin.
The reason there is a pwmio_dis command after the LEDs are faded all the way out is because the PWM function needs to be disabled in order for the chip to go into sleep mode. Even though the LEDs are essentially off (PWM set to zero), the PWM function is still enabled so the chip won't go to sleep. So we disable the PWM before calling the "end" command.
The {}p syntax is used when you want to have a path run in the background while the main program continues to execute. In the case of the lightsaber program, we want the LEDs to fade in while the sound effect is playing, so that they are sync'd together nicely. So in the program we call {fade_in}p followed immediately by playing the lightsaber open sound effect. What this does is starts the {fade_in}p function (which runs in the background and controls the fading in of the LEDs) while the main program path moves on and executes the sound effect. This way they have the appearance of happening simultaneously.
; background functions for fading the LEDs in and out
{fade_in}p:
& pwmio4=X0 ; set PWM on pin P3.3 to the value in X0
& delay(0.010) ; delay to control fade in time
& X0?254:stop_fade ; if upper PWM is reached (254), jump to stop_fade: label
& X0=X0+1 ; if not, increment PWM
& fade_in ; continue fading in
{fade_out}p:
& pwmio4=X0 ; set PWM on pin P3.3 to the value in X0
& delay(0.010) ; delay to control fade in time
& X0?0:stop_fade ; if min PWM is reached (0), jump to stop_fade: label
& X0=X0-2 ; if not, decrement PWM
& fade_out ; continue fading out
stop_fade:
& stop_p ; stop the backround equation
The {fade_in}p path continues to run separately on its own, controlling the fade-in of the LEDs, until the counter reaches 254. At that point "stop_fade" is called and the stop_p command is executed. The stop_p command stops any program paths that are running in the background, but the main program path keeps running.
