Thebridge's scripting capability provides users with the ability to customize and enhance the operation of thebridge by the addition of external programs. External programs can be used to add new user commands, as well as monitor and control the operation of thebridge. Ham radio is (should be) about experimentation, hopefully this capability combined with your imagination will lead to some interesting new applications for thebridge. Just get you going here some of the things that the Beta testers have been doing: 1. Tony VK3JED has used the scripting hooks to interface thebridge with his IRLP node to allow incoming and outgoing connections to his node from the EchoLink network. 2. Lee N2LEE/N4LED has used scripting to automate the recording of nets. He also uses scripting to automatically bring specified repeaters into the nets. 3. James KD6HWC has used the scripting to generate a web page that shows who is connected to his conference in real time. The web page also includes an password protected administrator interface for him that allows him to control thebridge via the web. There are two sides to the scripting interface, the event hook and the external command interface. They are completely independent, you can use one or the other or both. External Command Interface -------------------------- There are two ways for external programs to control thebridge, the easy way and the hard way. Which method is easy and which method is hard depends greatly on the user's experience and viewpoint. At the lowest level thebridge listens to a UDP port on the local machine (only) for commands. Users that have network programming experience may find this to be the easiest way to communicate with thebridge. Users without network programming experience may prefer to use the tbdcmd command line utility that is included in the release. The external command interface is disabled by default, to enable it add the following to your configuration file: CmdPort = 5198 This specifies the UDP port number that thebridge will use for communications with other programs ON THE SAME MACHINE. Since I have made no attempt to secure the command port thebridge only listens to the loopback port. This prevents commands from being sent thebridge from other computers. Other port numbers can be used if desired, 5198 is simply the default for tbdcmd. When the command port is enabled in the configuration file thebridge listens for ASCII commands to be sent to it on the specified UDP port. Command results are sent in a single UDP packet back to the originating port. All commands return one or more lines of data in the packet. Each line is delimited by a newline (0x0a) character. This first line is a numeric result (in ASCII) code with zero meaning successful command completion. Remaining lines contain any output the command generates. When enabled by the .chat command text messages received from the net are sent asynchronous to the command port prepended by an error code of 200010. When the chat mode is active text not proceeded by ".." are sent as text messages. Therefore the only way out of chat mode is to enter the command "..chat off". Although the normal mode of operation does not require dots to be prepended to commands they are allowed so there is no need to track the chat mode state. NB: Although the .chat mode feature is still supported it is depreciated. Version 0.84 and later of thebridge provides a separate port for text messages to replace the .chat mode. Error Codes ----------- 0 - Command executed without error 200001 - command not found or ambiguous 200002 - command requires disk and disk is disabled 200003 - Specified station not found 200004 - no info available for station (.info cmd) 200005 - invalid command argument count 200006 - Already connected (.connect cmd) 200007 - no one is talking (.mute cmd) 200008 - invalid command argument 200009 - error opening a file 200010 - Chat text 200011 - Timeout waiting for response from tbd. 200012 - Chat text sent tbdcmd ------ The tbdcmd command line utility is provided to allow external programs or scripts to control the operation of the thebridge without having to deal with network programming. Almost any programming or scripting language include some way to execute a command line program. Tbdcmd can be used in either a command at a time mode or interactively. The interactive mode is a convenient way for an administrator to control thebridge locally without having to connect to the conference via EchoLink. The command at a time mode is probably the most convenient mode for scripting. To use tbdcmd interactively just start thebridge and run tbdcmd. You should be able to enter command just like you do via EchoLink. The dot is optional since *only* commands are sent, not message text. Hit control-C or enter a blank line to exit. You can also run tbdcmd with a command to execute on the command line. For example: "tbdcmd help". The exit code will be 0 if the command is ok, otherwise one of the error codes listed above will be returned. Tbdcmd writes all output to stdout. Output can be capture using I/O redirection provided by the operating system or scripting language. For simple scripts the completion code may be sufficient. Usage: tbdcmd [-p] [-q] [-s] [-S] [-t] [commands] -p - Specify cmdline port (default 5198). -q - Quiet, numeric result code only. -S - Allow conference bridge's station list (default is suppress). -s - Slient, suppress banner. -t - Add timestamps to text chat messages. tbdchat ------- The tbdchat command is an alias for tbdcmd that uses port 5199 by default. The chat interface is disabled by default, to enable it add the following to your configuration file: ChatPort = 5199 Event Hook ---------- Thebridge that can also be configured to call an external scripts or programs when "interesting" things happen. To enable Event Hooks set the configuration file variable "EventScript" to the full path of the script or program to execute. The first argument on the command line given to the script will always be the event type, the rest of the command line depends on the event type. In general the event script should not generate any console output since thebridge normally runs as a daemon in the background without a console. Since thebridge waits for the script to finish before executing it again for the next event the script should exit immediately after performing it's function. Delays in script execution will not adversely effect normal operation of thebridge, it will only delay future event notifications. The following events are defined currently: Event: "connected" Arguments: This event is generated when a new user connects to the conference. is the type of connection which can be "speakfreely", "rtp", "echolink", or "outbound". "outbound" means the connection was a result of a previous ".connect" command and infers a EchoLink connection. is the callsign of the user that connected. is the number of total number of users connected to the conference. Event: "disconnected: Arguments: This event is generated when a user leaves the conference. can be "bye" when a user disconnects normally, or "rtcp_timeout" when the user times out. is the number of total number of users connected to the conference. Event: "playbackcomplete" Arguments: This event is generated when a file playback is completed. can be "CreateNewClient() failed" (an internal error), "starting new playback" (user did a new .play before the previous playback ended), "stop command", "playback complete", "write error 1" (disk write error during a .test command), "write error 2" (disk write error in another place in the code), or "rtcp timeout". Event: "command" Arguments: [] This event is generated when a user enters an *undefined* command. This allows thebridge's built in command set to be extended by external scripts. This feature might be used to define macros such as ".netstart" which might, for example, automatically connect to other nodes which wish to be brought into a net. are any arguments that were entered by the user. Event: "hostfile" Arguments: (none) This event is generated when thebridge updates the *nix style hostfile when thebridge has been configured to generate one. Event: "starting" Arguments: (none) This event is generated when thebridge starts up. Event: "shutdown" Arguments: (none) This event is generated when thebridge shuts down. Special commands useful for in scripts ".message [message text]" This command sends a text message to all stations connected to the conference.