Use the Instrument Addon to communicate with VISA, RS-232, or GPIB devices by adding a message group, creating and configuring messages and responses, and defining MetaData Channels. You must add instruments, as described in Adding LAN/SCPI Instruments with NI-VISA, Adding Serial Instruments with RS-xxx, or Adding GPIB Instruments with RS-xxx to GPIB ConvBox, before configuring the Instrument Addon.

  1. From the VeriStand Editor, launch System Explorer.
  2. Expand Controller and select Custom Devices » an Instrument Addon in the configuration tree.
  3. Right-click the Instrument Addon and select Add Group to add a message group.

    You must have a message group to create messages. A message group contains any number of messages. Creating message groups is an organizational element for commands. It allows the user to group commands logically. You may opt to group messages by channel (for example, CH1, CH2, and so on) or by type (for example, Configure, Control, and so on). For example, a two-channel power supply could be configured to have two groups—one for each channel. Each group contains the same messages, but configured for each channel.

  4. Right-click Message Group and select Add Message to create a message.
    Figure 1. Add Message


  5. Configure Command and Response as required for your message:
    • Write-only messages—Configure Command and delete Response.
    • Read-only messages—Configure Response and delete Command.
    • Query (write-then-read) messages—Configure Command and Response.
  6. Select Message in the configuration tree to configure the message generation settings.
    Figure 1. Message Configuration Page


  7. In the Message Configuration window, choose the Generation Type:
    Generation TypeDescription
    Trigger Only The most common generation type. Select for single event messages. For example, setting the instrument configuration at the beginning of a test.
    Periodic & Trigger Features the same triggerable function as Trigger, but automatically executes the message after a set period. When you trigger the message, the periodic timers reset. Selecting this generation type requires that you also set the Period in milliseconds. For example, if you have a period of 1 second and do not trigger the message, it automatically executes.
    Note You can control the periodic generation starting and stopping through the Enable Periodic channel.
  8. Specify the Value Change & Trigger.
    This features the same triggerable function as Trigger, but automatically executes the message when one of the command’s MetaData Channels changes value. Selecting this generation type requires that you also set the Period in milliseconds.
  9. Disable Include Protection to automatically include message protection. Use message protection to ensure that sent and received data match. Common protection schemes include checksums or CRCs. To enable this, check Include Protection and select the desired type. The protection is automatically calculated and placed at the end of the message.
    Note Limit the number of periodic messages for slower protocols and baud rates because this could delay other messages.
  10. Select Command in the configuration tree to create a message command. Or, if no command is required, right-click the item and select Delete.
    Command defines what strings and VeriStand data are sent to the instrument. If desired, you can make the command static.
  11. Configure the following:
    Figure 1. Command Configuration Page


    1. Enter a (case-sensitive) command equation in the Command field using [] to mark variables. For example, a command VRANGE[CH]:[VALUE] has variables CH and VALUE. Variables are linked to MetaData Channels which can be written to by the user, allowing the user to set a voltage range on a specific channel. NI recommends that you parameterize the commands with variables. Use [] to mark the variables in the command, then link those variables to your MetaData Channels in the custom device through the Linkages table.
    2. Select the variable ([]) from the Linkages field that you want to link to and then select the desired MetaData Channel from Available MetaData Channels.
      Note As an example, you can enter VSET1:10.000 to set the voltage range on channel 1 V to 10 V. However, if you do this, you will need to create the same message for any additional channels or ranges (for example, VSET2:10.000).
    3. Enable Pad to set a message length (required by some instrument protocols), and then set the desired Length (Bytes) and Pad Value.
      Note Length is total message size including any message protection. Enter 26 as the length for a message of 24 bytes of data and 2 bytes of protection.
    4. Create a command variable, also known as MetaData, by right-clicking a Command or Global MetaData Channels in the configuration tree and selecting Add MetaData Channel.
  12. Select Response in the configuration tree to create a message response. Or, if no response is required, right-click the item and select Delete.
  13. Configure the following:
    Figure 1. Response Configuration Page


    1. Enter a (case sensitive) response equation in the Response Format field using [] to mark variables. This format defines how to parse data out of the response string and into VeriStand data channels where commands are the reverse. For example, a command VRANGE[CH]? with a response [RANGE] has the response variable RANGE.
      NI recommends that you parameterize the responses with variables. Use [] to mark the variables in the response and then link those variables to your MetaData Channels in your custom device through the Linkages table.
    2. Select the variable ([]) from Linkages that you want to link to and then select the desired MetaData Channel from Available MetaData Channels.
    3. Specify the Wait Type to define the parameters of a response:
      • Wait Sec—Set a wait time value in seconds. The response waits that number of seconds, then reads the available bytes at the port.
      • Byte Count—Set a value in number of bytes. The response waits up to 10 seconds for the selected amount of data to be available, then reads just that amount of data. Set the Wait sec Value field accordingly.
    4. Disable Use Channel to use a channel for a set wait value, which allows you to change the number of bytes or wait time on the fly.
    5. Create a Response Variable, referred to as data, by right-clicking a Response item in the configuration tree and selecting Add Data Channel.
  14. Create a MetaData Channel:
    1. Right-click Command and select Add MetaData Channel.
    2. Configure the Channel Type. Set the MetaData Channel to format a particular variable into a string. This value is converted to the selected type and added to any configured string:
      • Enumerated List—Converts the numeric value of the MetaData Channel to an associated string value. It is 0 indexed. For example, if you have the command OUT:[ENABLE], where ENABLE is OFF or ON, you can set the list to OFF, ON. When the message is triggered, if the channel’s numeric value is 1, OUT:ON is sent. If it is 0, OUT:OFF is sent.
      • Format—Converts the metadata numeric value to a numeric string of that format. For example, a Format String of %x converts the numeric value to a hexadecimal string of that value (a value of 10 becomes A in the command string).
      • Type Cast—Converts the numeric value of the MetaData Channel to its binary representation. For example, to type cast a double, it would be converted to 8 bytes of binary data.
  15. Expand Message in the configuration tree and select Message Channels to configure message interaction and feedback:
    • Enable Periodic—Allows you to control when the periodic generation starts and stops. Only use if the message Generation Type is set to Periodic & Trigger. For example, to configure the instrument first, then periodically read from it, keep this channel low (0) until you are ready to read. Then set it high (1).
    • Error Code—Reports when the message was successfully executed. If this channel is 0, everything executed correctly. If it is a number, there was an error. The number indicates the error code reported. For example, after Message Status channel goes to 1, you can check this channel.
    • Message Status—Shows the current execution status of a message. The channel value goes to 0 while the messages is generated. The value goes to 1 when the message has been completed.
      Note The Message Status channel does not indicate a successful transfer, only which message is currently being executed. Use the Error Code channel for successful transfer messages.
      Note For commands with no response that has been sent before (meaning its value is already 1), you will see a constant channel value of 1 (instead of transition from 1 to 0 to 1) because of the transition speed.
    • Timestamp—Shows the timestamp of a message. The channel value updates after a response is received. If no response is configured, it updates after the command is sent.
      Note The Timestamp channel does not indicate a successful transfer. Use the Error Code channel for successful transfer messages.
    • Trigger—Triggers the configured message. Set the channel value to 1 to generate the message as configured. After the trigger is detected, the channel value sets back to 0 automatically.
  16. Create a Global MetaData Channel:
    1. Right-click Global MetaData Channels and select Add MetaData Channel. Global MetaData contains all the global inputs that can be used in commands. Define any command parameters here that can be reused in multiple messages.
      For example, most instruments are multiple channel. The commands for these devices require the channel number as part of the command. Therefore, you could create a global MetaData Channel named CHAN with a format of %d. This would then be used in any messages that require a channel. For example, VSET[CHAN]:10.000 sets the voltage output to 10 on whatever CHAN is selected.
    2. Configure the Channel Type. Set the Global MetaData to format a particular variable into a string. This value is converted to the selected type and added to any configured string:
      • Enumerated List—Converts the numeric value of the MetaData Channel to an associated string value. It is 0 indexed. For example, if you have the command OUT:[ENABLE], where ENABLE is OFF or ON, you can set the list to OFF, ON. When the message is triggered, if the channel’s numeric value is 1, OUT:ON is sent. If it is 0, OUT:OFF is sent.
      • Format—Converts the metadata numeric value to a numeric string of that format. For example, a Format String of %x converts the numeric value to a hexadecimal string of that value (a value of 10 becomes A in the command string).
      • Type Cast—Converts the numeric value of the MetaData Channel to its binary representation. For example, to type cast a double, it would be converted to 8 bytes of binary data.
  17. Save the system definition file.