Two Way Strings Version 2.7

This driver opens a serial, TCP or UDP port. The user can then send a string through that connection.

Transmit Strings: Strings to be sent can be specified in two ways:

All strings, including the start and stop characters, can be ‘escaped’ to allow the user to specify hexadecimal numbers. For example, if the desired string is PWR/r/n, the escaped version of that string is PWR%0D%0A.

Command Strings: Command strings are given names and defined in the configuration panel. They then become commands that show up in the Macros Steps editor in your Button Properties, or in the Library Window, under the Macro Steps tab. If you are using a pre-APEX version of ID they will show up as Driver Commands in the Library browser. Those commands can be used directly in a macro. In ID9.xx and earlier they can be dragged directly onto a button

Beginning in V2.7 you can create commands that have parameters available when entered from ID rather than the configuration. These parameters can be integers sent as ascii, a single byte, sent as a hex byte, or a string.

Raw Strings: For quick, one-off commands, the string can be specified directly as a parameter of the 'Raw Strings' command. This lets you do quicker, on-the-fly editing, but these command strings will not be saved when the driver configuration is saved

Receive Strings: The user can specify up to 100 RX strings which, if matched to any part of a received string, will cause events and create variables. Multiple user specified RX strings can be matched to one received string, causing multiple events to occur.

Example:

- User Specified String 1: PWRON

- User Specified String 2: PWROFF

- User Specified String 3: MUTEON

- User Specified String 4: MUTEOFF

- RX String from Device: #:PWRON:MUTEOFF:TNR09250

- In this situation, String 1 and String 3 would match, causing Event 1 and Event 3 to fire.

Wildcard: Beginning in V2.7 the driver recognizes the character sequence $$*$$ as a wildcard. When that sequence is entered into the RXString definition, the string will match regardless of the character at that spot. This can be used when the messages coming back that have a generally standard response but may have a character or two that vary slightly.

Example:

- User Specified String 1: MSG$$*$$XPORT

- Matched with: SMG0XPORT=Play or

- Matched with: SMG1XPORT=Play or

- Matched with: SMG2XPORT=Pause

PING: There is also a 'PING' string that can be configured to be sent at the specified interval. This can be used to poll the device for its status. Setting the interval to 0 disables this feature.

String Variables: The Configuration Window has a section called "RX String Variable Boundaries". Each matched string gets a prefix and a suffix. The 'matched' returned string is compared against these strings and any characters between them are written to the RX String Variable. A carriage return will always terminate a variable name so there is no need to add them as a suffix.

If there is neither a prefix nor a suffix, a string variable will not be created.

The wildcard sequence ($$*$$) can also be used in a suffix or prefix if needed, and it will match any character in the received string. As many wildcard sequences as needed can be used.

Integer Variables: When a string variable is created the driver also attempts to create an integer variable. Having an integer variable allows you to tie a value to a graphic or a gauge. If it can create an integer (the string must begin with it will write that to the RX Integer Variable. Each RX String has an Integer Multiplier associated with it, by default this is a 1. If the device returns a floating point number you can multiply it by some multiple of 10 to make sure you get all the digits and then use ID to display the integer with the correct number of decimal places.

In the sample, returning the string N S[1].mode="SiriusXM" when the input changes to SiriusXM will create a string variable but no integer variable will be written.

The player returns this string: N C[1].Z[1].volume="16" (for example) when the volume changes This will trigger RX String 6. RX String 6 has a suffix of volume=" and a suffix of just ", so the String variable will be 16. This will probably serve in most instances but if you want a volume gauge you cannot use a string so an integer must be created.

Boolean Variables: Boolean variables are created just like string variables, but the configuration allows you to enter a string that will be returned when that variable should be true. The player in the sample returns N C[1}.Z[1} playStatus="playing" when it is in play so the true value is set to “playing”, creating a boolean variable that can be used to reverse the play button. The sample file also shows several strings for the 'source', or the currently playing service of the player.

Dynamic Image Variables: Many devices, particularly media players, can return the URL of a thumbnail image that can be displayed on the panel. When the variable type is set to Dynamic Image, the URL is captured the same way any other string is, but will be passed to the panel to be displayed

In TCP mode, the ‘Connection’ boolean is true when the TCP connection is up and false when the TCP connection is down. In serial mode, the boolean becomes true after the first matched RX message is received.

Saving the Configuration (mini-driver): If you are going to be using this driver with a device you will be using in more than one project, or more than once in a single project, you can use the 'Export Configuration...' option under Driver Utilities in the Driver Configuration section. Saving this file lets you create a 'mini-driver', with all the commands and status you need, that you can then load into multiple projects.

Communication Options:

UDP: There is an option to open the port as UDP rather than TCP for devices that require those commands. UDP is a connectionless protocol. This means the driver effectively becomes a one-way driver. It does bind the port in the config file however, so if the device sends a return to that port it MAY work. These devices are rare however and the UDP mode should be considered a one-way connection.

Framing: You may add optional start and stop characters to 'frame' the messages the driver receives. The XP forwards data to the driver in finite chunks. For short strings these usually are a complete message (but there is no guarantee). Longer messages may arrive at the driver in multiple chunks making it difficult for the driver to find the strings it's looking for. Many devices frame their messages with specific characters so it's easy to tell where they start and end. These characters can now be entered into the driver. Although they are single characters, they are entered the same way the strings are, hex characters must be escaped. If you are expecting strings that end in cr/lf you would enter %0a as 0x0a is the ascii value of the line feed.

FRAMING NOTES

1) These are single characters, not strings -- if your string ends with a cr/lf combination just enter the line feed (%0a).

2) Start characters are only available if you ALSO specify a stop char. You CANNOT have just a start character.

3) At 9600 baud the driver may receive data in chunks as small as 10 characters. If your strings are longer than that you will need to frame them.

Version 2.7

Adds variable types to allow boolean variables without events and flags, and dynamic images for cover art images supplied by the device under control. Adds parameters to transmit strings, primarily to allow sending commands with a slider, but also to allow the commands inside the driver to act more like 'real' driver commands, with parameters. Adds wildcards to commands in both tx and rx strings.

Version 2.6

Expands the number of strings, variables, and events to 100. Adds the command strings to the configuration

Version 2.4

There are no functional changes to the driver in this release. The changes are simply to improve the driver’s usability. This version adds:

Dynamic Configuration: Variables and events only show up when they are in use.

Reorganized Configuration: The driver configuration has been reorganized.

Version 2.3

This version adds string and integer variables

Version 2.2

This version added framing support and a UDP messaging option