BEEPER functions of the terminal

(only available on certain programmable terminals)

Overview

To produce sounds with the beeper, two interpreter commands are available for the terminals which have a beeper (or "speaker") built inside.

Note:: Terminals without a beeper don't understand these commands, the interpreter may display an error then !

The commands are:

beep( <frequency> [ ,<time> [,<volume> [ ,<frequency_mod> [ ,<amplitude_mod> ] ] ] ] )
Only the first parameter is mandatory, the rest is optional. See examples below. The "beep" command can be abbreviated as "be".
play( <string of tones>)
Can be used to play a ringer tone, alarm, or a short melody. See examples below.

More examples for the 'beep'- and 'play' command can be found in the installation under programs/BeepTest.cvt .

The "beep" command

Produces a single tone, which may be sweeped in frequency.

Syntax (in the display interpreter, not in the script language ):

be( <freq> [,<time> [,<volume> [,<fm> [,<am> ] ] ] ] )

Parameters:

freq: Tone frequency in Hertz. A value of zero turns the tone off, if no other parameters follow.
Caution: The lowest possible audio frequency is 366 Hz for devices with 24MHz CPU clock and 610 Hz for devices with 40MHz CPU clock. If the frequency cannot be realized due to hardware restrictions, the "closest possible" audio tone will be produced.
time (optional): length of the tone, measused in 100-millisecond-steps. If this and all following parameters are missing, the tone will be "endless" until you turn it off with the command beep(0) or be(0).
volume (optional): Relative volume (loudness) in percent, ranging from 0 to 100. The beeper is controlled with a pulse width modulator which can be used to produce different output levels, but the harmonic spectrum of the generated tone is also affected by the PWM duty cycle. A volume of 100 produces the loudest possible tone with a 1:1 duty cycle.
fm (optional): Frequency modulation. Can be used to produce siren-like sounds, or "chirps" and "whistles". Unit is "Hertz per 100 milliseconds". If the value is positive, the frequency increases as long as the sound is audible; if the value is negative the frequency decreases.
am (optional): Amplitude modulation. Can be used to produce sounds which start with a low volume and then get louder. Not very effective because of the pulse-with modulation, where a volume of 10% can hardly be distinguished from a volume of 50% . On the PC (similator), amplitude modulation is impossible. A tone on the PC speaker cannot be pulse width modulated.

Examples for the "beep" command:

be(1750): starts an endless tone with 1750 Hz, and maximum volume
be(0): stops any previously started tone
be(1750,5): produces a single, unmodulated 'beep' (calling tone) at 1750 Hz, 0.5 seconds long.
be(150,20,50,100): produces a 2-second, "chirped" tone which rises from 150 Hz to 2150 Hz (=150 + 2 seconds * 100 Hz/0.1sec).

The "play" command

Produces a sequence of tone, which may be a ringing tone, an alarm, or a short melody.

Syntax:

pl( <string> )

The string is a sequence of letters and digits with the following meaning:

a...l: 12 halftones of the first octave. 'a'=262 Hz, 'b'=277 Hz, .... 'j'=440 Hz, 'k'=466 Hz, 'l'=494 Hz.
(Note that the letters have nothing to do with the historic names of the harmonic scale,
and some devices cannot produce these low frequencies !)
m...x: 12 halftones of the second octave. 'm'=523 Hz .... 'x'=988 Hz.
A...L: 12 halftones of the third octave. 'A'=1046 Hz .... 'L'=1975 Hz.
M...X: 12 halftones of the fourth octave. 'M'=2093 .... 'X'=3951Hz.
' ' (space character): inserts a pause in the played melody, using the current duration value
0...9: Set the duration of the following notes and pauses:
'0' = the sortest possible note (depending on the timer interrupt, 10 milliseconds on most terminals)
'1' = 50 milliseconds
'2' = 100 milliseconds
'3' = 150 milliseconds
'4' = 200 milliseconds
'5' = 400 milliseconds
'6' = 600 milliseconds
'7' = 1000 milliseconds
'8' = 1500 milliseconds
'9' = 2000 milliseconds
!vN: volume. N=1 produces weak tones, N=9 the loudest tone. Note: The pulse-width m
!aN: attack interval. Parameter 'N' defines, how fast a tone's amplitude rises from zero to the maximum (value of !v).
!dN: decay interval. Parameter 'N' defines, how fast a tone's amplitude falls from maximum to the sustain level.
!sN: sustain level. For continuous tones. The command !s0 produces tones without a sustain level, like bells, piano etc. See 'big ben' example.
!rN: release interval. During this time, a tone's amplitude drops from the sustain level to complete silence.
!lN: loop. N=1...9 defines the count of repeats. The end of a loop must be marked with "!le" (loop end). Loops in a melody string cannot be nested.

Notes:

There is no automatic gap between notes !
To compose melodies, in earlier program versions (designed for Windows 98 and XP), you could use the simulator ("View"..."Test Command Window"). But since neither the 'SmallPort' utility (which granted direct access to the PC's I/O registers for the hardware timer) work unter recent windows versions anymore, you can only 'compose' on a real target.

Examples for the "play" command (abbr. pl)

pl("5m4o5qo2 5rq4ol5m")
(german national anthem)
pl("!v9!d7!s0 6qmo9h6 hoq9m")
(Westminster chimes, aka "Big Ben" melody, full volume)
pl("!v3!d7!s0 6qmo9h6 hoq9m")
(the same with lower output 'volume'; in fact just a different PWM duty cycle so the tones will sound different)

More examples for the 'play' command can be found in the installation under programs/BeepTest.cvt .
The command is also available in the script language as system.play_notes.

Legal Terms

See main manual.

Last modified: 2010-03-16 (YYYY-MM-DD)