Amxd API

author:  Erik Machnicki
last modified:  05/05/01



Introduction:

Amxd is a server that runs on the machine connected to the AMX through
a serial port.  It provides remote access to the AMX through the TclDP
RPC mechanism.


Connecting and Sending Commands:

You can connect to the amxd either using DpClient (mash) or directly
using the dp-lib.tcl (tcl) library.  Examples in the command section
will show how to use in Mash, then from Tcl.

Mash:

To connect to the amxd using Mash, you should use the DpClient mash
object, which is a wrapper for the TclDP interface.

	import DpClient

	set hostname htsr.bmrc.berkeley.edu
	set port 6901
	set amx_ [new DpClient $hostname $port]

To issue commands, use DpClient's do() or doNoWait() functions.

	$amx_ do command_string	 

where command_string is any amxd server command you want executed.
(see below)

Tcl:

To connect to the amxd using just plain tcl, you should source
mash/lib/tcl/dp-lib.tcl.

	source <your-path-to-lib>/dp-lib.tcl

	set hostname htsr.bmrc.berkeley.edu
	set port 6901
	set client_ [dp_MakeRPCClient $host $port]

To issue commands, use TclDP's dp_RPC or dp_RDO commands.

	dp_RPC $client_ command_string

where command_string is any amxd server command you want executed.
(see below)

Note that in both cases, you must specify a hostname and port #.
Currently, amxd runs on htsr.bmrc.berkeley.edu/6901.


Server Commands:

There are several commands which the server recognizes:

amxd_getVersion
    - args:
	no arguments
    - return values:
	version number
    - desc:
	returns the version number of the amxd server running
    - ex:
	set ver [$amx_ do amxd_getVersion]
	set ver [dp_RPC $client_ amxd_getVersion]

matrix library - commands to control the matrix switcher's video
	         input/outputs.  See matrix-lib.txt for more info.

matrix_switchVideoStream input output {projectorScanConverted 0}
    - args:
	input - [mbonePC, sgiPC, frontPC, liveboard, laptop, rackVCR,
		 frontVCR, speakerCamera, wideCamera, audienceCamera,
		 elmo]
	      - which input source should be connected to output
	output - [htsr, htsr2, projector, realNetworks]
	       - which output source is being changed
	projectorScanConverted - [0,1]
			       - specifies whether RGB inputs should
				 be scan converted and displayed as
				 video, or the RGB signal should be sent
				 directly to the projector
    - return value:
	none
    - desc:
	Routes the specified input to the specified output.
    - ex:
	$amx_ do matrix_switchVideoStream frontPC htsr
	dp_RPC $client_ matrix_switchVideoStream frontPC htsr

matrix_getInputSource output
    - args:
        output - [htsr, htsr2, projector, realNetworks, testMonitor]
	       - which output source you are interested
    - return value:
        input source
    - desc:
        Looks up which input is routed to the specified output and
	returns the input source.
    - ex:
	set main_input [$amx_ do matrix_getInputSource htsr]
	set main_input [dp_RPC $client_ matrix_getInputSource htsr]

	

amx library - commands to send direct commands to the AMX.
	      Eventually, clients should not need to use this library,
	      all functionality will be in libraries such as matrix
	      and camera.

send-AMX-command cmd device chan_str
    - args:
	cmd - [1, 2, 4-7, 10]
	    - 1 => channel on
	      2 => channel off
	      4 => send string
	      5 => send command
	      6 => push channel
	      7 => release channel
	      10 => pulse channel
	device - [1-15, 128, 129]
	       - which AMX device to deal with
	chan_str - [1-255, string]
		 - cmd = (1, 2, 6,7,10) => device channel to operate on
		   cmd = (4, 5) => string to send to the device
    - return value:
	"Sent AMX command" or an error
    - desc:
	Sends the specified command to the AMX (see AMX
	documentation).

	This function should be replaced by various libraries that
	abstract away AMX.
    - ex:
	$amx_ do send-AMX-command 10 14 55
	dp_RPC $client_ send-AMX-command 10 14 55


camera library - commands to control the cameras in the room

camera_pulseMove id dir {numTimes 1}
    - args:
	id - [speaker, audience]
	   - specifies which camera to move
	dir - [left, right, up, down, in, out]
	    - which direction to move the camera in
	num_times - [1->] (default 1)
		  - how many times to execute the command
		  - specifying num_times does not result in predictable
		    behavior, because the camera control is not precise
    - return value:
	none
    - desc:
        moves the camera a small distance in the specified direction
    - ex:
	$amx_ do camera_pulseMove speaker left
	dp_RPC $client_ camera_pulseMove speaker left

camera_startMove id dir
  - args:
	id - [speaker, audience]
	   - specifies which camera to move
	dir - [left, right, up, down, in, out]
	    - which direction to move the camera in
    - return value:
	none
    - desc:
        starts to move the camera in the specified direction
	to stop the camera, call camera_stopMove
    - ex:
	$amx_ do camera_startMove speaker left
	dp_RPC $client_ camera_startMove speaker left

camera_stopMove id dir
  - args:
	id - [speaker, audience]
	   - specifies which camera to stop
	dir - [left, right, up, down, in, out]
	    - which direction to stop camera movement in
    - return value:
	none
    - desc:
        stops the camera from moving in the specified direction
    - ex:
	$amx_ do camera_stopMove speaker left
	dp_RPC $client_ camera_stopMove speaker left

camera_center id
  - args:
	id - [speaker, audience]
	   - specifies which camera to center
    - return value:
	none
    - desc:
        moves the camera to its home, center position
    - ex:
	$amx_ do camera_center speaker
	dp_RPC $client_ camera_center speaker

camera_setPreset id num
    - args:
	id - [speaker, audience]
	   - specifies which camera to set preset on
	num - [1-6]
	    - number of preset to set
    - return value:
	none
    - desc:
        sets the specified preset for the specified camera
	call camera_goPreset to return to the position at which the preset
	was set
    - ex:
	$amx_ do camera_setPreset speaker 3
	dp_RPC $client_ camera_setPreset speaker 3

camera_goPreset id num
    - args:
	id - [speaker, audience]
	   - specifies which camera to go to the preset on
	num - [1-6]
	    - number of preset to go to
    - return value:
	none
    - desc:
	moves camera to specified preset position
    - ex:
	$amx_ do camera_goPreset speaker 3
	dp_RPC $client_ camera_goPreset speaker 3


lights library - commands to control the lighting in room 405

lights_set setting
    - args:
	setting - [full, overlay, slide, off]
	   - specifies which lighting setting to go to
    - return value:
	none
    - desc:
        sets lighting to specified setting
    - ex:
	$amx_ do lights_set slide
	dp_RPC $client_ lights_set slide


scan converter library - commands to tune the scan converter

Not yet documented.


on air library - commands to control "On Air" warning light

Not yet documented.


VCR library - commands to control the VCR

Not yet documented.


callback library - commands to register callbacks to be called when an
		   AMX event is generated.

callback_register callback
     - args:
	callback - [tcl procedure taking one parameter]
		 - name of the procedure that will be called when AMX
		   event generated 
    - return value:
	none
    - desc:
	Register a function to be called by the amxd on the client
	when an AMX event is generated.  Note that this function is
	executed in the Tcl interpreter that the client runs in, NOT
	the amxd.

	The function registered will be called with one argument.
	That argument is a tcl list, detailing the AMX command,
	device, and channel/string parameters of the AMX event.  See
	AMX Events, below, for more details.

	Note that this function will not be called until a call to
	callback_enable is made.

	Note that this must be a regular tcl procedure, it cannot be
	an otcl class procedure.  Of course, the tcl procedure can be
	a wrapper that reads the global variable containing the
	instance and calls the class procedure.
    - ex:
	$amx_ do callback_register processAmxMsg
	dp_RPC $client_ callback_register processAmxMsg

callback_enable
    - args:
	none
    - return value:
	none
    - desc:
	Enable an already registered function to be called by the amxd
	when an AMX event is generated.

	Before callback_enable can be called, a function must first be
	registered with callback_register.
    - ex:
	$amx_ do callback_enable
	dp_RPC $client_ callback_enable

callback_disable
   - args:
	none
    - return value:
	none
    - desc:
	Disable an already registered function to be called by the amxd
	when an AMX event is generated.  This prevents an AMX event
	from causing a callback to be generated on the client.
	If no function has been registered, or if the callback is
	already disabled, this function does nothing.
    - ex:
	$amx_ do callback_disable
	dp_RPC $client_ callback_disable


Events:

Amxd allows clients to receive notification when certain AMX related events
occur, such as a user pushing a button on the touch panel, or an AMX
device generating a response.

See the event-api.txt file for more info.

A client registers a function to be called by calling
callback_register.  They can then allow callbacks to occur by calling
callback_enable.  When an AMX event occurs, the callback on the client
is called, and the tcl list with the event information is passed as
the argument.

An example illustrates how to use the callback features:

	   #
	   # foo.tcl
	   #
	   ...
	   proc myCallback { retList } {
		if {[llength $retList] != 0} {
			set eventInfo [lindex $retList 0]
			set type [lindex $eventInfo 0]
			set eventData [lindex $retList 1]
			set cmd [lindex $eventData 0]
			set dev [lindex $eventData 1]
			set chan_str [lindex $eventData 2]
			...
		}
	   }
	   ...
	   $amxd_ do callback_register myCallback
	   $amxd_ do callback_enable
	   ...

Now, when an AMX event is generated, an RPC call to myCallback will
occur, and myCallback will be executed on the client.

	   ...
	   # we don't care about AMX events anymore, so turn off
	   $amxd_ do callback_disable

Now, when an AMX event is generated, we will not be notified until we
re-enable the callback.

