Camera Remote Control Command Language ---------------------------------------- We are reserving three characters for use as delimiters in the messages sent between the camera control server and clients. These characters are #, @, and "; the # will be used to separate devices, the @ will be used to separate information about a single device and the " will be used to surround descriptions that are more than one word in length. This language will allow camera control user interfaces (clients) to converse with the device control server. It defines the format of messages sent between the clients and the server. The language does not explicitly support compound moves, but it allows multiple device movement requests to be incorporated in the same message and the device server will multiplex these commands as appropriate. All messages will be timestamped. This timestamp will either be a video frame number from vic or an NTP timestamp (still to be decided). Vocabulary ---------- Device types devserv (the device server itself) camera videoswitch . . . . (In the future we will probably include audio) Unit number - each device of a particular type will have a unit number. Degrees of Freedom for a Camera pan tilt zoom focus power xlocation (the camera may be a virtual camera that has 6 degrees of freedom) ylocation zlocation roll . . . . (In the future, all the stuff the sony supports) Degrees of Freedom for a Switch camera fade wipe pnp (picture-in-picture) ..... (In the future, all the stuff the Panasonic supports) Command Syntax --------------- Each device command is specified to be using relative, absolute, or fraction of the current image values. The device movement commands are specified by [] The fields have the following meanings device type - camera, videoswitch, . . . unit number - the devices of a particular type are numbered starting at 1 degree of freedom - the setting that is to be modified. On a camera this might be pan, tilt, zoom, or focus. method of specification - this is relative, absolute, or fractional. Relative is taken from the current position, absolute uses the device 0 position as its reference, and fractional is specified in terms of the current image generated by the camera as seen by the user. Alternatively, this field can contain the word home indicating the degree of freedom should return to its specified home position. move specification - this is the actual amount you want the device to change. In the case of a camera pan axis this will be a value in degrees. The move specification can be multiple fields and varies by device and degree of freedom. Some move specifications allow a variable number of fields. (see examples below) NOTE: Each field of the command can be abbreviated to the shortest string that allows it to be uniquely recognizable. Three letters will always be sufficient to distinguish a command field. The fields of the command are separated by white space. Numeric fields can be specified as floats or integers but if a float is provided in a field where an integer was expected, the float will be truncated to form the integer. Device command Examples To pan camera one by 10 degrees at a speed of 12. cam 1 pan R 10 12 To zoom camera 3 to 6 X magnification. cam 3 zoom A 6 To turn off power on camera 2 cam 2 power A on NOTE: An additional degree of freedom called "home" is also defined to allow a device and all of its degrees of freedom to be reset to the home position. An example command would be cam 1 home Message Syntax -------------- All Messages The lines of a message are separated by the # symbol. For all messages, line 1 contains the following fields (acts as a header) message length - including all lines (not including this field). this field is 4 bytes long and is an int32 in network byte order. timestamp - this will either be an NTP timestamp or a vic video frame number (still to be decided, it probably will be a vic frame number) devserver name - identifies this particular server for use if we are going to allow multiple servers on the same multicast address. Messages sent to the Server - Requests Each of the lines after line 1 defines either a single device command or a series of commands for the same device. If it contains a single command for a device then the syntax is as specified in the section above. If the line contains a series of commands for the same device then the commands are separated by the @ symbol and the commands following the first command in the series specify the device command only from the degree of freedom field to the end of the command. Alternatively, line 2 can be specified as devserv home This command results in all of the devices connected to the server being reset to their home positions. Or, line 2 can be specified as devserv description This command causes the server to send a Description message. Messages sent by the Server - Description Line 2 message type (description) Line 3 devserv information which includes an optional text description, the version number, and the supported features. If included, the text description must be enclosed in double quotes; if not included, the default is "NONE". If more than one feature is supported, "@" will be used to separate the features. Examples are: "Conference Room" V.4.4 CIF@Akenti "NONE" V.4.4 CIF "Conference Room" V.4.4 Line 4 reference vic/data address, port, and ttl slash delimited and source machine of camera Line 5 contains the identification of the last command accepted including requestor and timestamp. The format is: " " \ If there are multiple devices, they will be separated by "@". If the server has not received a request, the command identification will be "NONE". Each of the lines following line 5 are used to indicate the devices and the status and bounds of each of their degrees of freedom. These lines are formatted similarly to the lines of a request. \ \ [ ] \ [ ] device type - camera, videoswitch, . . . unit number - the devices of a particular type are numbered starting at 1 unit description - text enclosed by "" describing the unit. If the description is a single word then the quotes are not necessary. degree of freedom - the setting that is to be modified. On a camera this might be pan, tilt, zoom, or focus. current value - current position of the device. lower limit - lowest position value that the device supports upper limit - highest position value that the device supports The following fields will only be present if appropriate for the particular device degree of freedom. current speed - current default speed setting. lower speed limit - lowest speed value that the device supports upper speed limit - highest speed value that the device supports current accel - current default acceleration setting lower accel limit - lowest acceleration value that the device supports upper accel limit - highest acceleration value that the device supports If a device supports multiple degrees of freedom, the degrees of freedom will be separated by the @ symbol. Messages sent by the Server - Status This message is smaller than the Description message and may not be needed if the Description message is to be used to indicate status. The primary reason we would need to switch to using Status is if the Description message becomes larger than 1k. Line 2 message type (status) Line 3 contains the identification of the last command accepted including requestor and timestamp. (This is the same as for Description messages.) Each of the lines following line 3 are used to indicate the devices and the status. These lines are formatted similarly to the lines of a request. \ [][] See the Description message for definitions of these fields. If a device supports multiple degrees of freedom, the degrees of freedom will be separated by the @ symbol. Messages sent by the Server - Busy This message will only be generated if needed in practice. Currently it is not defined because we do not expect to need it. Messages sent by the Clients - Info This message is sent by the client periodically to register that this client is currently in the process of controlling the camera system. The purpose of this message is not to establish exclusive control but to allow the user to register the fact that they are currently working with the camera so that other people will know that there is someone who currently thinks they are controlling the cameras. We expect that this message would be generated based on the status of a user settable interface. Line 2 message type (client) Line 3 client identification information Line 4 control status (watching, waiting to control, controlling) Communication Mechanisms ------------------------ As a first pass at the communication mechanisms, all messages from the clients to the server will be sent using UDP. All messages from the server to the clients will use an IP multicast. Initially the messages sent by the server are always the Description message. They are sent on completion of execution of a request from a client, when a client explicitly requests a description, or after an elapsed time period (e.g., after 7.5 minutes) if not sent otherwise. In the future, we plan on the server's sending Status messages when a request has been carried out or after a time period has elapsed and sending Description messages only when requested. Units and specifications for commands referring to a particular degree of freedom --------------------------------------------------------------------------------- Camera degrees of freedom degree of fdm. posn units range other info -------------- --------- ----- ----------------- pan,tilt degrees +,- values speed, acceleration can be specified (range 0-1.0) zoom magnification 1-x focus distance 0-x position can be specified as auto to turn on autofocus. If position is specified as manual the camera will switch to manual focus. If a specific focus command is given it switches to manual focus. power state off/on, or 0,1 Videoswitcher degrees of freedom degree of fdm. posn units range other info -------------- --------- ----- ----------------- camera integer 1-x video bus specified by letter (A,B,...) fade ???? wipe ???? degree of fdm. feature posn range other info -------------- -------- ---- ----- ---------- pnp camera integer 1-n camera to put in pnp. pnp state off/on, or 0,1 pnp translate X Y 0-1.0 X and Y location of upper left corner of pnp window on picture. pnp size W H 0-1.0 width and height of pnp window in picture. NOTE: for the purposes of pnp the origin (0,0) of the coordinate system will be the upper left corner of the outer image. The x axis positive direction will extend to the right and its value will be 1.0 at the right edge of the outer image. The y axis positive direction will extend down and its value will be 1.0 at the bottom edge of the outer image. All values can be given as relative or absolute values where the R or A is specified after the feature designator. ex. vid 1 pnp cam 1@pnp sta on@pnp tra A 0.45 0.55@pnp siz A 0.45 0.40 (would completely specify a pnp window in the lower right hand corner displaying camera 1)