This chapter covers the structure of older Wings Platinum *.ptd drivers. If you want to create a new driver you should use the more up-to-date Avio driver model. See Creating your own Avio driver.
Opening an existing *.ptd driver in a text editing program allows you to see what its structure is like. Available drivers can be found by clicking Extras in the main menu - Open folder 
Drivers. A driver contains a description at the beginning, followed by the commands in the order they are to appear in the selection menu. Every line may contain any sort of comment, which must be separated from the command by two slashes. Look at the example below: //This comment is for your information only and will not be evaluated.
[Driver]
This ID in the first line is compulsory.
Name=XXX
Name of driver or device to be controlled
Date=XXX
Date of creation
Author=XXX
Name of the person creating the driver
Comment=XXX
Any comments on the driver
All the above information will be visible in Wings Vioso RX in the Properties Dialog Serial Port after selecting the driver.
ID used last=XXX
Specifies the ID used last. This way the author knows which IDs have already been used when he adds further commands. It should always be kept up-to-date and is used for the information of the author only.
The following parameters are used for interface configuration. If you know which parameters a device requires it may be useful to specify them here.
Network=X
With X=1 the LAN interface is preset; with X=0 or if the parameter is skipped, the interface is RS232.
NetworkIP=XXX.XXX.XXX.XXX
The specified IP address is the default setting in the dialog.
NetworkPort=XXXXX
The specified port is the default setting in the dialog.
NetworkUDP=X
With X=1, the UPD protocol is preset, with X=0 the TCP protocol.
DefaultPollInterval=X
Defines the default interval for polling parameters; X is entered in seconds. If this parameter is missing, the default interval is 20 seconds.
In the driver file, a complete block of information might look as follows:
[Driver]
Name=AV Stumpfl EventPlayer
Version=1.00
Date=26.04.2004
Author=Christoph Hilger
Comment=Basic control of EventPlayer software
ID used last=10
Network=1
NetworkIP=10.10.68.11
NetworkPort=18000
NetworkUDP=0
DefaultPollInterval=20
Separated by a blank line, this is followed by an obligatory command block for sending any character strings that can be entered in the driver dialog at a later time:
[SendData]
Info=Sends raw data
ID=1
SubID=0
Par1=Data, Data to be sent to Device
Send=#Data(Par1)
This can be followed by further command blocks separated by a blank line each.
Character strings for serial commands can be entered in a variety of forms; even mixed entry is possible:
Decimal notation is directly accepted.
ASCII characters must be entered between quotation marks. Bytes must be separated by a separator (space or comma).
For input of hexadecimal values, every byte must be marked as "Hexbyte". This can be done by adding the following characters: 0x12, h12, 12h or $12 (in our examples 12 is the byte information).
First of all, we would like to illustrate the basic structure of commands in a driver. At the end of this topic you will find a few examples of drivers that do not use all the options available and actually show how simple the commands are structured. Please make sure you write any information and comments in English so that the drivers can be used internationally.
[Command name:Subname]
Command name displayed for selection in the context menu. Separated by a colon, a optional subname can be entered to be displayed as a submenu.
ShortName=XXXX
For optional entry of a short name to be shown in markers and control panel fields (preferably 10 characters only). This is very useful for very long command names and submenus. For commands including parameters, the parameters are displayed after the short name, i.e. just like for the SC Master 16 driver for Card Volume to Value, where two parameters (for card player and value) must be entered: Vol crd 3, 25
Info=XXXX
Information to be displayed as comment in the driver dialog when this command is selected.
Icon=X
Specification of an icon; X stands for the index of one of the icons listed here. When no icon is specified, Icon=0, i.e. the standard icon 
, is used automatically.
ID=1
Every command must have a unique ID number between 1 and 255, which must not be used for any other commands in the driver. Important: When you modify a driver, do not alter the IDs of any existing commands. Otherwise the driver will be incompatible with any earlier driver versions!!!
SubID=1
Related commands can be structured on a second level by adding a sub-ID between 1 and 255, which has them displayed in the submenu of the context menu, too. The sub-ID within an ID number must be unique. SubID=0 means no sub menu. Important: When you modify a driver, do not alter the sub-IDs of any existing commands. Otherwise the driver will be incompatible with any earlier driver versions!!!
Par1=Format (VX, Y, Z), name of entry field
Allows parameter entry in the driver dialog. "Format" specifies the type of information to be expected; VX is the value address (e.g. V3); the admissible range is defined by Y (minimum) and Z (maximum). The following parameters are possible:
Data ... max. 255 characters in accordance with defined data format, mixing of ASCII, Hex, etc. is possible
Number (Y, Z); the driver dialog will display a number entry field. The range of values needs to be defined, e.g. Number(1,255)
Value (VX, Y, Z) uses the value at address X based on the value range of X and Y, with Y=0% and Z=100% of a data object, e.g. Value (V3, 1, 3456). This is how you can define the output range for data objects or control panel fields. See also Variable data output by means of drivers.
This way three different parameters can be used (Par1 to Par3). For Value parameters you need to additionally define a DriverLoop command for time control. In a parameter line, too, although separated by a comma, the part following after is the name of the entry field in the driver dialog.
If you are using more than three parameters and want to use this driver for older projects (...created by Wings Vioso RX 2.40 or earlier), you should definitely test the functions extensively. Otherwise there may be compatibility problems.
Send=Character string
As character string up to 255 characters can be sent. Entry can be in mixed notation in accordance with the data format defined. Adding command
#Pause(X)
to a character string creates a pause with a duration of X (entry in milliseconds between 1 and 255) at this location when sending the command.
Variable parameters (Par1 to Par8) can be integrated as follows:
#Data(Par1)
The character string for parameter 1 is evaluated as mixed notation and sent in hexadecimal values.
#Byte(Par1)
As above, but with only the first byte of parameter 1 being sent.
#WordBE(Par1) or #Word(Par1)
As above but the first two bytes of parameter 1 are sent in the specified order (big endian).
#WordLE(Par1)
As above, but with the first two bytes being interchanged (little endian). This version is to be used for sending commands in Wings Vioso.
#LongBE(Par1) or #Long(Par1)
Similar to #WordBE but the first four bytes of parameter 1 are output in the specified order (big endian).
#Long(Par1)
Similar to #LongBE, but with only the first four Bytes being sent in reverse order (little endian). This version is to be used for sending commands in Wings Vioso.
#Decimal(Par1)
The character string for parameter 1 is output as ASCII characters.
#Decimal:Decimal position(Par1)
As above, but specifying the decimal position that needs to be sent. Decimal positions between 1 and 100,000 can be specified. This is a useful option when devices require individual bytes, i.e. the keystroke on a remote control unit.
Acknowledgements of the device following receipt or execution of commands can be evaluated. The driver description should contain information about whether this function has been programmed for the user to know whether an activation of Acknowledge in the driver dialog actually makes sense.
ReceiveAck=XXX
Here you enter the character string the device sends back upon receiving a command.
ReceiveTimeout=XXX
This command is for defining the period (in milliseconds) for Wings Vioso RX to wait for the acknowledgement. After expiration of this period, an entry is made in the log file and, if applicable, the command is resent (Retries=?). Allows sufficient time for the receiving device to recognize the command and to send an acknowledgement.
ExecuteAck=XXX
Here you enter the character string the device sends back upon executing a command.
ExecuteTimeout=XXX
Just like ReceiveTimeout, but refers to the execution of a command.
Retries=X
This entry allows you to define the number of times a command is to be repeated if no acknowledgement is received within the specified period of time. For Retries=2, the command is sent three times at a maximum.
PollInterval=X
If a value different from the default interval should be used for the polling command, you can enter individual pooling intervals in seconds. Polling is not performed with a value X=0.
In combination with parameter Value you can use command DriverLoop to define the circumstances when the data are to be sent. This command is, therefore, an internal instruction for other commands.
[DriverLoopX]
Internal command, with X (1...255) being the index for differentiation between different command blocks.
ID=X
SubID=X
ID and SubID define the command the DriverLoop command is to take effect on.
Interval=XXXX
This entry defines the frequency with which values are to be sent. Entry is in milliseconds.
SendAlways=X
Here you can define whether values are to be sent always (X=1) or only after having changed (X=0).
Example of a complete command with DriverLoop
Serial ports of SC Net components are not suitable for DriverLoop commands. For this purpose use the serial ports of PC hardware.
Below you will find a few examples of drivers used for our EventPlayer software. The command block below is used for sending a simple command. Here it is the play command for the current folder of the EventPlayer software. In hexadecimal values it is FF 01 04 FE.
[Play]
Info=Starts playback of current folder
Icon=1
ID=5
SubID=0
Send=0xFF 0x01 0x04 0xFE
Should the play command for the EventPlayer software refer to a particular folder, the folder remote index must be contained in the command. This is done by entering parameter 1. Moreover, submenu Folder should be displayed in the context menu Play. This can be achieved by specifying a subname. The specified short name makes sure that the whole information including folder index is visible, e.g. Play fold 14. As this is also a play command, the same ID was used but with a different sub-ID. For entry of parameter 1, number format and a range from 1 to 255 were selected. The command contains #Byte(Par1) for the remote index. This causes only the first byte of the entry field information in the driver dialog to be evaluated.
[Play:Folder] //This comment is not displayed in the driver dialog.
Info=Starts specified media folder
ShortName=Play fold
Icon=1
ID=5
SubID=1
Par1=Number(1,255), Remote index of media folder
Send=0xFF 0x02 0x04 #Byte(Par1) 0xFE
This command block initiates evaluation of an acknowledgement for correct reception of the command. This requires the last three lines. At ReceiveAck the character string sent back by the device is entered. Allow enough time for Receive Timeout (500 ms in this case), otherwise commands may be sent several times due to retries. When the expected acknowledgement does not arrive within the specified time, Wings Vioso RX makes an entry in the log file.
[Load Project]
Info=Loads predefined project
ShortName=Load P
Icon=19
ID=10
SubID=0
Par1=Number(1,255), Number of predefined project
Send=0xFF 0x02 0x0A #Byte(Par1) 0xFE
ReceiveAck="OK" 0x0D 0x0A
ReceiveTimeout=500
Retries=2
You should write your first driver for a device whose protocol you are familiar with. If there are any problems in controlling the device, debugging is much easier because you need to concentrate on the driver and its syntax only.
After you have made alterations to a driver used in an open project, you need to reload the project for the driver to be reloaded and the alterations to take effect. You don't need to do so if you open the driver as follows:
In the Media Pool click on the plus sign next to 
Devices and select the required Serial/LAN port.
In the right Media Pool section, right-click the serial port and select Properties.
Click on 
Edit driver, edit and save the driver.
In the Wings Vioso RX dialog click OK. Following this you can use the driver and its functions.
See also
Selecting icons for driver commands