NAME

Palantir.conf - configuration file for Palantir

DESCRIPTION

The file palantir.conf provides configuration parameters and device definitions for the palantir server. The default location of this file (usually '/usr/local/share/palantir/palantir.conf') is determined at compile time; an alternate file can be specified via the -C command-line option to palantir.

It is perfectly legal to run palantir without a config file. If, however, one is (explicitly or implicitly) supplied which is not properly written, palantir will refuse to start and complain loudly.

Most parameters can be set both via a command-line option and in the config file. When there is a conflict between the two definitions, the command-line option takes precedence.

Some parameters (e.g. device definitions) can only be set in the config file. Conversely, not all command-line options have their config file counterpart (yet).

FORMAT

Each line in the palantir.conf file starts with a keyword followed by one or more parameters. No line breaks are allowed between a keyword and its parameters, or between parameters. Use spaces or tabs to separate them.

Keywords are case-insensitive.

String parameters which include spaces must be delimited by double quotes (``).

If the first non-whitespace character in a line is #, that line is considered to be a comment, and all subsequent characters until end-of-line are discarded.

A device definition is introduced by the keyword Device. The actual definition must be included in curly braces.

A configuration file consists of zero or more global options, defining video, audio and network parameters and general setup, and zero or more device definitions, describing the server-side devices which clients can interact with. The next two sections give a comprehensive overview of the keywords available in each context.

GLOBAL OPTIONS

VideoDevice dev: Capture video from device dev. Default is to capture from /dev/video0.
Channel ch: Capture video from channel ch. Default is to capture from channel 0. The number of available channels depends on the capture device selected; a list of the available channels for a given device is displayed as diagnostic output at startup. For most Bt8x8-based cards, channel 0 is the TV tuner, channel 1 the composite input, and channel 2 the S-Video input. On the other hand, most webcams only provide a single channel. Your mileage may vary.
FrameRate fps: Set the capture frame rate to fps frames per second. Currently, this option has only effect with USB cameras supported by the pwc driver.
Palette palette: Select video palette. palette can be Mono or Color, to capture grayscale or full-color frames, respectively. Monochrome capture can help reducing video bandwidth (although not dramatically).
FrameSize NxM: Set the frame size to NxM. Due to hardware limitations of the capture device, the actual frame size may differ from the requested one. Most webcams for example allow only a very limited set of capture boxes, while Bt8x8-based cards are usually able to accommodate for a much wider size range. Look for the actual capture size in the diagnostic output, after the first client connection.
ImageFilters filter [ filter ... ]: Apply the specified filter chain to the captured frames. Currently supported filters are Flip (reverse the image horizontally), Invert (reverse the image vertically), and UpsideDown (equivalent to Flip Invert; useful if your camera is mounted rotated 180 degrees).
JPEGQuality quality: Set the JPEG compression quality level to quality, expressed on the 0...100 scale recommended by the Independent JPEG Group. Default value is 50.
TunerFreq frequency: Tune the video device to frequency (in MHz). If the video device has no tuner associated with it, this setting is ignored.
VideoNorm norm: Set the TV video norm to norm, which can be one of PAL, PAL-NC, PAL-M, PAL-N, SECAM, NTSC, NTSC-JP, or AUTO. Default norm is PAL.
Audio state: This directive is deprecated and has no longer effect. Prior to Palantir 2.7, it was used to enable or disable the audio channel. Starting with version 2.7, audio streaming is disabled by default, and has to be enabled by specifying one (or both) of AudioCaptureDevice and AudioPlaybackDevice (see below).
AudioCaptureDevice dev: Enable the audio stream from server to client, using dev as capture device. Can be used in conjunction with AudioPlaybackDevice, which enables audio from client to server. If the sound card supports full-duplex operation, AudioCaptureDevice and AudioPlaybackDevice can refer to the same device.
AudioPlaybackDevice dev: Enable the audio stream from client to server, using dev as playback device. Can be used in conjunction with AudioCaptureDevice, which enables audio from server to client. If the sound card supports full-duplex operation, AudioCaptureDevice and AudioPlaybackDevice can refer to the same device.
VideoAudioInput index: Select audio input index on the video capture device. Default is to use device 0, which is often the only audio device (if any) on the capture card. Note that to effectively capture audio from the video device, the corresponding channel on the main system mixer - typically labeled ``Aux'' or ``Video'' - should be (manually) enabled for capture.
VideoAudioVolume level: Initialize the volume of the audio input device to level (in the range 0...65535). Default value is 65535.; See also VideoAudioInput.
AddressFamily family: Define which IP address family (i.e. IPv4 or IPv6) the server will listen on. family can be inet (use IPv4 only), inet6 (use IPv6 only), or any (listen on both IPv4 and IPv6 addresses through the IPv6 interface). Default value is any.
TCPPort baseport: Set the TCP base port to listen on. palantir requires one TCP port for the HTTP stream (which carries video and data channels) and another one for the audio stream (unless the audio channel is disabled or not available). By default, the latter binds to baseport+1; a different port can be specified on the command line or in a TCPAudioPort directive. Default base port is 3000.
TCPAudioPort audioport: Set the TCP audio port to listen on. Default is baseport+1 (usually 3001).; See also TCPPort.
SerialPort dev: Set the serial port device to dev. palantir will use this serial port to control (and get data from) any external device implementing the Palantir Device Protocol (defined in the next section). Default is not to use a serial link.
ControlTimeout timeout: Set the duration (in seconds) for control time share. After gaining control, a client will retain it until this timeout period expires. Then, if there is some other control request pending, the client will be preempted. If the control queue is empty, however, the client will keep control indefinitely (until another request occurs). Default is 30 seconds.
ClientTimeout timeout: Set the timeout (in seconds) for client connections. After this interval, the client will be forcibly disconnected, regardless of whether it is currently in control or not. Default is to allow indefinitely long connections (no timeout).
ClientAckTimeout timeout: Set the timeout (in seconds) for frame acknowledgement. Stand-alone clients acknowledge every frame received from the server, in order to keep latency to a minimum; if this timeout expires before the acknowledgement is received, the client will be forcibly disconnected. Default is 30 seconds; unless you are streaming large frames over very slow links, you might want to keep it lower (say 15 seconds).
MaxStreamingClients clients: Set a limit to the number of simultaneous connections to the video stream. Connections in excess are not rejected; instead, new clients are served a snapshot. Default is to allow an unlimited number of simultaneous connections to the video stream.
LogFile filename: Set the log file path. To facilitate log rotation, this file is closed and reopened when the server gets a HUP signal. Default is to write log messages to the standard error output stream.
Greeting string: Set the message sent to clients upon connection. It is up to the client to decide whether (and how) to display this message or not. Default is ``Experimental Palantir server''.
NamedPipe file: Set the location of the named pipe used for communication with software devices. Default is not to use a named pipe.

DEVICE DEFINITIONS

In the following, by device we mean a communication endpoint, exposed by some piece of hardware or by a software process, which the palantir server can exchange data with.

Read and ReadWrite devices (see the Direction directive) can supply data to the palantir server, which will in turn broadcast them to all connected clients. ReadWrite devices can, in addition, be operated through the server by the client currently in control.

Each device is uniquely identified by specifying in a Carrier directive the link it uses to communicate with the server and the address (an integer index) relative to that link. palantir currently supports three families of communication links:

Serial, for true hardware devices connected to the server via a serial port (see the SerialPort global option);
Pipe, for software devices (i.e. external processes) communicating with the server by means of a named pipe. The location of this file is set via the NamedPipe directive (see GLOBAL OPTIONS above). Devices of this type can presently only be read from, not written to (see the Direction directive);
Internal, for run-time manipulation of some palantir parameters (e.g. video brightness). See the Carrier directive for a complete listing.

The list of directives available in a device definition follows.

Carrier link addr: Associate this device with address addr (which must be an integer number greater than or equal to 0) of link link (which can be one of Serial, Pipe or Internal).; On the Internal link, address 0 is associated to video brightness (in the range 0...65535), address 1 to video contrast (same range), address 2 to video color (same range), address 3 to the video tuner frequency (the presets are defined in frequencies.h and represent a selection of TV stations available in Italy), and address 4 to the input channel (the range starts from 0 and depends on the input channels available on the device). Addresses 5 and 6 currently refer to the pan and tilt built-in motors for the Logitech QuickCam Sphere/Orbit cameras, but this mapping may change in the future.; This directive is mandatory in every device definition.
Direction dir: Define data direction for this device. dir must be either Read or ReadWrite (or their abbreviations R, RW). Default is Read.; For devices on the Pipe link, only the Read value is allowed.
Name string: Assign symbolic name string to this device. string should be a terse description of the device's function, which some clients could display as a short textual label along the device's visual representation.; The names ``Pan'', ``Tilt'' and ``Zoom'' have a somewhat peculiar meaning; see the Visual directive for details.; See also Hint below.
Hint string: Define a hint for this device (typically a longer description of its function than the one given by Name). Clients can choose to display either the device's Name, or its Hint, or both of them, or none at all.
Visual type: Define a visual representation (control) for this device. type can be one of Slider (with variants Slider_x, Slider_y, Slider_z) or Gauge. The Slider representation gives the user the ability to check the device's value as well as to operate the device by dragging a cursor (the device's Direction must be defined as ReadWrite, i.e. there must be some kind of actuator associated with it). Slider_x, Slider_y and Slider_z represent three special sliders to be displayed on the client's main window at some predefined positions - a horizontal bar below the video frame, a vertical bar on the right of the frame, and a shorter bar somewhere else, respectively. These sliders are usually (but not necessarily) associated with pan, tilt and zoom controls. The Gauge representation simply displays the device's value in a gauge-like fashion; it offers no means of interacting with the device.; The choice of available controls is likely to expand in the future.; This directive is mandatory. However, for compatibility reason, if the device Name is one of ``Pan'', ``Tilt'' or ``Zoom'' and no Visual is specified, the default value of Slider_x, Slider_y, Slider_z, respectively, will be assigned. Please do not rely on this behaviour, as it will most likely change in the future.
Range min max
Remap n1 n2: These directives set a linear transformation between values as read from (or written to) the device and as presented to the user by the client.; Range declares that device data of interest to the user lie in the range min...max instead of the default 0...65535. min and max must be integer numbers, with max strictly greater than min.; Remap linearly rescales the min...max range to n1...n2. Here n1 and n2 can be floating point numbers and n2 can be less than n1.; Clients will associate the left (or bottom) end of the graphical control for this device (as specified in the Visual directive) with n1, and the right (or top) end with n2. Device data received by the client will be level-shifted and scaled according to the transformation specified by Range and Remap before being presented to the user (in graphical or numerical form).; The actual transformation is described by the formula; displayed value = (device value - min) * (n2 - n1) / (max - min); If Remap is not specified, it is assumed that n1=min and n2=max.; If Range is not specified, it is assumed that min=0 and max=65535.
Notifier source: This setting affects how a value change for this device is propagated to connected clients. source can be one of None, Device or Client. None causes neither data originating from this device nor data sent to it by the controlling client to be broadcast to connected clients. Device causes data originating from the device to be broadcast to all connected clients. Client causes data sent to the device by the controlling client to be broadcast to all other connected clients; it is the way to go if this device does not provide feedback on updates (as is currently the case with the special devices on the Internal link).; Default value is Client for devices on the Internal link, and Device in all other cases.

EXAMPLES

The following definitions describe two devices for controlling camera pan and tilt, respectively. The hardware is supposed to be connected to the server via the serial link; an on-board microcontroller is required to dispatch data to the appropriate device according to its address (0 for the pan and 1 for the tilt stepper motors):


  Device {
     Carrier Serial 0
     Direction ReadWrite
     Visual Slider_x
     Name "Pan"
     Range 20 230
     }

  Device {
     Carrier Serial 1
     Direction ReadWrite
     Visual Slider_y
     Name "Tilt"
     Range 20 230
     }

Direction is set to ReadWrite to enable clients to control the devices.

The values Slider_x and Slider_y for the Visual directive tell clients to display two ad-hoc sliders below and on the right of the video frame for the ``Pan'' and ``Tilt'' controls.

The Range directive restricts the control range to 20...230 from the default 0...65535. As a consequence, when the pan scrollbar is dragged full left on the controlling client, the microcontroller will be commanded to set the pan stepper motor to position 20 (or to position 230 if the scrollbar is dragged full right). The same holds for the tilt control (which will be displayed as a vertical scrollbar instead).

The implicit Notifier Device directive states that notification of a device status change is expected to come from the device itself. In this case, after a position change the microcontroller should provide feedback to the server about the motor's new position. The server would in turn broadcast the information to all connected clients, which would adjust the position of their sliders to reflect the change. If the device were unable to provide feedback and still you wanted changes committed by the user in control to be propagated to all other clients, Notifier Client should be explicitely used instead.

The following device definitions are suitable for the pan and tilt controls featured by the Logitech QuickCam Sphere and Orbit webcams:

  Device {
     Carrier Internal 5
     Direction ReadWrite
     Name "Pan"
     Hint "Camera pan"
     Range -7000 7000
     Notifier Client
     Visual Slider_x
     }

  Device {
     Carrier Internal 6
     Direction ReadWrite
     Name "Tilt"
     Hint "Camera tilt"
     Range -3000 2500
     Notifier Client
     Visual Slider_y
     }

Since the pan/tilt hardware provides no position feedback, Notifier Client is required here.

The following definition describes a thermal probe located at address 3 on the serial link. Let's assume that temperature data supplied to the server are in Celsius degrees (in the range 0...100), but clients are required to display them in the Farhenheit scale.

  Device {
     Carrier Serial 3
     Direction Read
     Name "Temp"
     Hint "Room temperature in Farhenheit degrees"
     Visual Gauge
     Range 0 100
     Remap 32 212
     }

The Remap directive does the range conversion trick from 0...100 (Celsius) to 32...212 (Fahrenheit).

AUTHOR

David Santinoli <palantir at santinoli.com>.