Writing your own Avio driver

You want serial control of a device via the Avio system but there is no driver available yet - why don't you just write your own driver by means of a text editor. All you need to know about is the device protocol and the way an Avio driver is structured. The latter you will find out about in this chapter. Once you have written a driver we are asking you to make it available to us so that we can build up a database all Stumpfl users can benefit from, See also Available drivers. So if you should require a driver next time maybe somebody else has already done the job for you, too.

Structure of a driver

When you use a text editor to open an existing driver you can see what its structure is like. Available drivers can be found by clicking Extras - Open folders Drivers in the Wings Vioso main menu. Make sure you open a driver with the extension *.asd (Avio Serial Driver). An Avio driver contains a description at the beginning, followed by the commands in the order they are to appear in the Avio Manager. 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

Version=X.X

Driver version

Date=XX.XX.XXXX

Date of creation

Author=XXX

Name of the person creating the driver

Comment=XXX

Any comments on the driver

The following parameters are used for interface configuration. If you know which parameters a device requires it may be useful to specify them here.

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.

ConnectionType=X

For X=UDP the UPD protocol is preset, while X=TCP presets TCP protocol and X=RS232 the RS232 protocol.

DefaultPollInterval=X

Defines the standard interval used for polling the parameter; X is entered in seconds, for X=0 no polling occurs. The standard polling interval can be overwritten by individual polling intervals in ever command.

In the driver file, a complete block of information might look as follows:

[Driver]

Name=Canon WUX450

Version=1.00

Date=21.11.2013

Author=Dieter Hartmann

Comment=Basic control of Canon XEED WUX450 projector

NetworkIP=???????

NetworkPort=?????

ConnectionType=UDP

DefaultPollInterval=10

This can be followed by command blocks separated by a blank line each.

Data format

Character strings for serial commands can be entered in a variety of forms; even mixed entry is possible:

Structure of a command block

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.

[Gruppe:Channel]

The name of the channel is the name of the command to appear in Avio Manager. As an option, it can be preceded by group name separated by a colon. In Avio Manager all channels of the group are listed in one folder even when the commands in the driver are not arranged on below the other.

Par1=Format (Y, Z), name of the parameter in Avio Manager

Allows parameter entry in Avio Manager. "Format" specifies the type of information to be expected; the admissible range is defined by Y (minimum) and Z (maximum). The following formats are admissible:

Data ... max. 255 characters in accordance with defined data format, mixing of ASCII, Hex, etc. is possible

Number (Y, Z), entry of values; entry of the range of values is optional, e.g. Number(1,255)

This way up to eight different parameters can be used (Par1 to Par8). In a parameter line, although separated by a comma, the part following after is the optional name of the channel in Avio Manager.

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.

Variable parameters (Par1 bis Par8) can be integrated as follows:

#Data(Par1)

While receiving or sending, the character string 1:1 is sent or passed on to Avio as text.

#Byte(Par1)

As above, but with only the first two Bytes of parameter 1 being output.

#WordBE(Par1) or #Word(Par1)

As above but the first two bytes of parameter 1 are output 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 ASCII character string is interpreted as a figure.

 

Evaluation of acknowledgements

Acknowledgements of the device following receipt or execution of commands can be evaluated.

ReceiveAck=XXX

Here you enter the character string the device sends back upon receiving a command. Up to nine parameters can be contained in the received string (Ret1 toRet9), e.g. ReceiveAck=0x00 #byte(Ret1) #byte(Ret2)0x01. This information can be displayed as channels in Avio Manager. Characterization of the information to be expected (#byte in our example) is done as explained for the parameters.

Now you can define the way the received information is to be displayed in Avio Manager:

Ret1=Name(Y,Z)

The name is displayed as the channel name in Avio Manager. The value range of the values to be expected from the device can optionally be specified with Y (Minimum) and Z (Maximum). This makes sense as it allows the Avio system to scale the correct range automatically for other channels.

Wildcards (*) are supported within the specified return parameter. Locations with a wildcard * accept any string in the received acknowledgement. A practical example might be a return value, for example, which is sent at the end of a checksum which may differ every time. In order to recognize the received return message a * is added at the end of the specified return parameter, i.e. the received value may contain any characters at the location of the asterisk but will still be recognized as the specified return value.

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.

 

Examples

Below you will find a few examples of drivers used for Wings Vioso. The command block below serves for sending a simple command. Here it is the Play command for the current timeline in Wings Vioso. In Hex it is as follows: FF 01 04 FE

[Play]

Send=0xFF 0x01 0x04 0xFE

 

If the Play command is to refer to a particular location the remote indexes of timeline and position marker must be contained in the command. This can be achieved by entering parameters.  The number format and a value range from 1 to 250 were selected. The command contains #Byte(Par1) or #Byte(Par2) respectively, for the two remote indexes. This causes only the first Byte of the entry field information in the driver dialog to be evaluated. In contrast to the example above the command name is preceded by a group name in the example below.

[Play:Timeline and Position Marker]

Par1=Number(1,250), Remote index of Timeline

Par1=Number(1,250), Remote index of Position Marker

Send=0xFF 0x02 0x04 #Byte(Par1) #Byte(Par2) 0xFE

 

This command block polls the operating time of a projector lamp and is supplied as channel in Avio Manager. The status can be displayed on the user interface. At ReceiveAck the character string acknowledged by the device is entered. Here the number of hours with the return parameter Ret1 is available as channel in Avio Manager.

[Get lamp counter]

Send="GET LAMPCOUNTER" 0x0d

ReceiveAck="g:LAMPCOUNTER=" #Decimal(Ret1) 0x0d

Ret1=LampCounter

PollInterval=10

 

Tips for creating your first driver

See also

Sending/receiving commands via the computer's LAN interface