Lark.mesa
Last modified by Swinehart and Owicki, December 7, 1982 1:47 pm
Last modified by Swinehart, June 14, 1983 11:30 am
Last modified by Stewart, July 18, 1983 12:58 pm
External interface to Lark (Etherphone) Capabilities (Smarts=>Lark)
This interface is a Lark private affair and makes no distinction between the
front and back doors. Such a distinction must be handled by the Smarts.
DIRECTORY
DESFace USING [ Key ],
PupTypes USING [ PupAddress ],
RPC USING [ Conversation, ShortROPE ],
RPCPkt USING [ Machine ];
Lark: CEDAR DEFINITIONS = {
-- *************************** Types ****************************** --
SHHH: TYPE = RPC.Conversation;
ROPE: TYPE = RPC.ShortROPE;
EncryptionKey: TYPE = DESFace.Key;
VoiceSocket: TYPE = PupTypes.PupAddress;
Machine: TYPE = RPCPkt.Machine;
noMachine: Machine = [[0], [0]];
Device: TYPE = MACHINE DEPENDENT {
microphonePTT (0), -- mike switch --
hookSwitch (1), -- switch on local handset
speakerSwitch (2), -- switch on speaker box --
touchPad (3), -- DTMF generator/detector --
keyboard (4), -- standard keyboard --
auxiliaryKeyboard (5), -- extra device
locator (6), -- as yet undefined --
ringDetect (7), -- on back door --
revertRelay (8), -- on Teleset, controls Tip, Ring, and receiver --
offHookRelay (9), -- on Telewall, controls Tip and Ring only --
sideTone (10), -- on Teleset --
ringEnable (11), -- volume bypass on speaker --
led (12), -- lamp on speaker box --
crossBar (13), -- analog crossbar switch --
timeslot (14), -- to set timeslots --
voiceMode (15), -- program modes --
inGain1 (16), -- table indicies --
inGain2 (17),
outGain1 (18),
outGain2 (19),
echoSuppression (20),
nothing (21),
clearCrosspoint (22), -- Event is row/column pair --
setCrosspoint (23), -- Event is row/column pair --
revertHookswitch (24), -- reverts A/A1, etc. --
aRelay (25), -- controls A/A1 --
tones (26), -- Event `disabled' means outstanding tone requests have all been satisfied --
delay (27), -- Event is number of deciseconds to delay --
spMode (28), -- speakerphone mode --
(255) -- byte wide --
};
Kinds of keystrokes and other "digital" actions that a Lark user might initiate,
including keyboard and touchpad buttons, switch-hook actions, etc. An event must
be associated with a Device in order to be unambiguously interpreted.
Event: TYPE = CHARACTER;
Ascii range
firstChar: Event = '\000;
lastChar: Event = '\177;
DTMF pushbuttons
b0:  Event = '\200;
b1:  Event = '\201;
b2:  Event = '\202;
b3:  Event = '\203;
b4:  Event = '\204;
b5:  Event = '\205;
b6:  Event = '\206;
b7:  Event = '\207;
b8:  Event = '\210;
b9:  Event = '\211;
bA:  Event = '\212;
bB:  Event = '\213;
bC:  Event = '\214;
bD:  Event = '\215;
bStar:  Event = '\216;
bThorp: Event = '\217;
Switches (i.e., offhood, onhook)
enabled: Event = '\220;
disabled: Event = '\221;
reset:  Event = '\222;
Time slots
ts0:  Event = '\223;
ts12:  Event = '\224;
Table indices
tab0:  Event = '\225;
tab1:  Event = '\226;
tab2:  Event = '\227;
tab3:  Event = '\230;
tab4:  Event = '\231;
tab5:  Event = '\232;
tab6:  Event = '\233;
tab7:  Event = '\234;
tab8:  Event = '\235;
tab9:  Event = '\236;
Voice software modes
o3i1:  Event = '\237;
o2i2:  Event = '\240;
o1i1:  Event = '\241;
Echo suppression modes
inbound: Event = '\242;
outbound: Event = '\243;
<<TEMP: Synthesized telephone number terminator>>
endNum: Event = '\244;
tag field in Generate tones
notify: Event = '\245;
Typically, devices and events will be combined
CommandEvent: TYPE = MACHINE DEPENDENT RECORD [
device: Device,
event: Event
];
StatusEvent: TYPE = MACHINE DEPENDENT RECORD [
time: CARDINAL,
device: Device,
event: Event
];
Subset of events corresponding to "touch-tones"
DTMFEvent: TYPE = Event[b0..bThorp];
CharacterEvent: TYPE = Event[firstChar..lastChar];
Sequences have these kinds of domain types, so that instances of them will
fit in a single RPC packet.
Passel: TYPE = [0..32);
This is basically an Event "string", maxLength=length
Good for sending character sequence, as in the Display command, below.
StatusEvents: TYPE = REF StatusEventSequence;
StatusEventSequence: TYPE= RECORD[
e: PACKED SEQUENCE length: Passel OF StatusEvent
];
CommandEvents: TYPE = REF CommandEventSequence;
CommandEventSequence: TYPE= RECORD[
e: PACKED SEQUENCE length: Passel OF CommandEvent
];
Hertz: TYPE = [0..3500); -- Voice bandpass --
Milliseconds: TYPE = [0..10000);
There may be more than one way to transmit voice, depending.
We will probably also experiment with a number of encodings.
Protocol: TYPE = MACHINE DEPENDENT {interactive (0), nWay (1), recordOnly (2), (7)};
Encoding: TYPE = MACHINE DEPENDENT {muLaw (0), (7)}←muLaw;
VoiceBuffer: TYPE = MACHINE DEPENDENT {in1 (0), in2 (1), out1 (2), out2 (3), out3 (4), (7)};
If a Smarts says this to a Lark, it informs the Lark what connections
to establish (see Connect, below.) If a Lark says this to a Smarts, it
is a report of what connections presently exist.
ConnectionSpec: TYPE = REF ConnectionSpecRec;
ConnectionSpecRec: TYPE = MACHINE DEPENDENT RECORD [
protocol: Protocol,
encoding: Encoding,
blankA: [0..1777B] ← 0,
sampleRate: INTEGER,
packetSize: INTEGER,
blankB: [0..17777B] ← 0,
buffer: VoiceBuffer,
blankC: [0..7777B] ← 0,
keyIndex: [0..17B],
localSocket: VoiceSocket,
remoteSocket: VoiceSocket
];
Some more stuff that the Lark tells the Smarts when Registering.
Genre: TYPE = MACHINE DEPENDENT { Alto (0), Lark1(1), (255) };
LarkModel: TYPE = MACHINE DEPENDENT RECORD [
genre: Genre,
hardwareVersion: [0..256),
softwareVersion: CARDINAL
];
KeyTable: TYPE = REF KeyTableBody;
KeyTableBody: TYPE = RECORD [
s: SEQUENCE size: [0..20B] OF EncryptionKey
];
EchoParameters: TYPE = REF EchoParameterRecord;
EchoParameterRecord: TYPE = MACHINE DEPENDENT RECORD [
blankA: [0..17777B] ← 0,
buffer: VoiceBuffer,
blankB: [0..37777B] ← 0,
buffer2Controlled: BOOL,
buffer1Controlled: BOOL,
decayTime: CARDINAL,
gain: ARRAY [0..5) OF CARDINAL
];
-- ************************ Smarts=>Lark procedures ********************** --
Cancel any tone sequence in progress. Clear the display (or set it to a distinctive
"out of service" state). Forget about any conversation in progress. Hang up any
automatically switched audio devices (Speakerphone, etc.) Remember the identity
of your "smarts". rName is for use in LarkSmarts.Register (cf.)
Reset: PROC [shh: SHHH, rName: ROPE];
Always accept, whether or not a conversation is in progress; return immediately,
f1, f2: frequencies of two sinusoidal tones; f2 may be zero to request a single tone.
modulation#0: tones alternate at modulation rate, equal duty cycle.
modulation=0: sine waves are added DTMF fashion.
on, off: noisy and silent intervals during each repetition.
repetitions: should be fairly small; longer sequences should be produced by queuing
multiple specifications, not too far ahead; prevents pollution after server crash.
waveTable, an index into Lark's available waveform tables for tone generation.
Also, more complex tone sequences can be specified using a queue of Tones requests.
queueIt: add specification to a list of sequential tone specs
~queueIt: supercede all pending tones with this one (e.g., scope=silence)
notify: issue a "tones" event when this entry terminates.
GenerateTones: PROC [ shh: SHHH,
f1, f2, modulation: Hertz,
on, off: Milliseconds,
repetitions: CARDINAL,
waveTable: CARDINAL,
queueIt: BOOLEANTRUE,
notify: CommandEvent ← [nothing, 0C]
]
RETURNS [ok: BOOLEAN -- FALSE means no room in queue --];
Standard DTMF is special; this function avoids long Tones[] sequences.
on, off: "make"/"break" intervals for each code.
waveTable, queueIt: as above.
events: a "string" of DTMF events to be "feeped". This is for back-door dialing, end-to-end
signalling for remote control of systems, etc. Each DTMF event reported via
LarkSmarts.RecordEvent may also have to be echoed by the Lark program, depending
on the nature of the keyboard.
notify: issue a "tones" event when all digits have been sent.
Feep: PROC[ shh: SHHH,
on, off: Milliseconds,
waveTable: CARDINAL,
queueIt: BOOLEANTRUE,
notify: CommandEvent ← [nothing, 0C],
events: CommandEvents
]
RETURNS [ok: BOOLEAN -- FALSE means no room in queue --];
Commands.
Commands: PROC [shh: SHHH, events: CommandEvents];
Use the sockets and the protocol type from |spec| to establish a conversation between
yourself and the indicated other party (ies). If a conversation is already underway,
replace it with this one, without disrupting existing conversations (a good trick, but
needed, since host number, socket number are likely to change.)
Connect: PROC [shh: SHHH, specs: ConnectionSpec];
Drop all connections corresponding to id, return to idle state. A Connect call with a zero-length
socket sequence should behave the same way. The buffer parameter should match the
connection specification that is being abandoned.
Disconnect: PROC [shh: SHHH, buffer: VoiceBuffer];
This is a Smarts request for the Lark to Register, thus providing a status update.
<< If it works out, the Lark should call LarkSmarts.Register BEFORE returning from
PleaseRegister. That may tie all the monitors in knots, or make error management yucky
on one end or other, whence a return from PleaseRegister will be taken as a promise
to register soon. Alternatively, the procedure could return registration info. >>
PleaseRegister: PROC [shh: SHHH];
This is a Smarts request for the Lark to send in its entire state.
A which = 0 indicates that the Lark should start over. Thereafter, LarkSmarts should
make the next call with which = next.
WhatIsStatus: PROC [shh: SHHH, which: CARDINAL]
RETURNS [next: CARDINAL, events: StatusEvents];
This is a Smarts request for the Lark to send in its outstanding connections.
A which = 0 indicates that the Lark should start over. Thereafter, LarkSmarts should
make the next call with which = next
WhatAreConnections: PROC [shh: SHHH, which: CARDINAL]
RETURNS [next: CARDINAL, specs: ConnectionSpec];
This is a Smarts request for the Lark to send in its outstanding tones.
For now just returns that there are some.
WhatAreTones: PROC [shh: SHHH] RETURNS [BOOLEAN];
SetKeyTable: PROC [shh: SHHH, table: KeyTable];
CommandString: PROC [shh: SHHH, device: Device, commands: ROPE];
After responding in the affirmative, Lark should collect user name and password information
(somehow), locally, use the Agent to obtain new authentication based on the password, issue LarkSmarts.LogIn to identify the new Rname, then begin using a new conversation based on the new authentication.
PleaseLogin: PROC[shh: SHHH] RETURNS [will: BOOL];
EchoSupression: PROC [shh: SHHH, echo: EchoParameters];
SetHostNumber: PROC [shh: SHHH, host: Machine];
}.
Stewart, July 18, 1983 11:09 am, added SetHostNumber