SDI-12 devices are some of the most commonly utilized instruments in Environmental Data Acquisition (EDA) applications. Organizations such as the National Weather Service, the US Geological Survey, the Environmental Protection Agency, and the National Ecological Observatory Network (NEON) employ these instruments to perform research on matters such as global warming, climactic change, water quality testing, and emissions monitoring. The NI LabVIEW SDI-12 API allows researchers, engineers, and scientists to combine the power of the NI LabVIEW graphical programming environment with any SDI-12 instrument to instantly create a customizable, software-defined SDI-12 acquisition system for any type of application. For more information on the SDI-12 API and the components necessary to build your system, refer to Building an Environmental Monitoring System for SDI-12 Devices.
This tutorial will illustrate how to acquire measurements from any SDI-12 instrument using the LabVIEW SDI-12 API, which can be downloaded from the NI Instrument Driver Network. The API is fully customizable and can be used in conjunction with any National Instruments Programmable Automation Controller, including Real-Time controllers. LabVIEW and the SDI-12 API also provide the ability to seamlessly interface with an assortment of hardware, including our data acquisition devices, modular instruments, and instrument control products. Visit the NI product pages for more information on these product platforms.
2. Acquiring Data using Measurement & Automation Explorer
First, you will need to configure your SDI-12 system. Refer to Building an Environmental Monitoring System for SDI-12 Devices to obtain information on the necessary components of the system and instructions on how to connect each component together. Once the system is connected, you’re ready to begin acquiring data from your SDI-12 devices.
Measurement & Automation Explorer (MAX) provides access to all of your National Instruments hardware and software products. MAX is automatically installed with any National Instruments driver or software product. You can use Measurement & Automation Explorer to configure your hardware setup, check driver versions, or create virtual channels and tasks for use with your applications. You can also use MAX to quickly test the functionality of your hardware or even to acquire data from DAQ devices or communicate with instruments connected to your computer.
In this case, we can use MAX to quickly and easily send SDI-12 commands to our SDI-12 instrument(s) using the VISA test panel. The Waterlog H-4191 converter creates a seamless connection between your RS-232 port and the SDI-12 instrument.
In the Configuration tree, navigate to Devices and Interfaces » Serial & Parallel. Then find the RS-232 port that is connected to your WaterLog H-4191 converter. In this example, we have chosen COM1. Click on the Port Settings tab and configure your RS-232 port as shown in Figure 1. Refer to the Waterlog H-4191 User Manual for more information on this device.
Figure 1. Serial Settings in MAX
After selecting the appropriate RS-232 interface and configuring the port settings, click the Open VISA Test Panel button to bring up the VISA Test Panel.
Determining Device Information
To acquire data from your SDI-12 instrument, click on the viWrite tab and type a command into the Buffer text-entry box. Refer to the manual for your SDI-12 instrument for your device’s command set. In this example, we have chosen to send the ‘0I!’ command to the Stevens Water Monitoring Systems Hydra-Probe II, where the ‘0’ represents the sensor address. This command prompts the Hydra-Probe II for its identification information. Once the command is entered into the text-entry box, click the Execute button.
Figure 2. Send Device Information Command in VISA Test Panel
To read the device information back from the instrument, click on the viRead tab. Enter the number of bytes you wish to read back from your instrument into the Count input and click the Execute button. The Buffer text box will display the contents of the serial buffer, which in this case corresponds to the Hydra-Probe II device information.
Figure 3. Device Information response
Reading Measurement Data
The process for reading measurement data is similar to the process for obtaining device information. First, enter an initiate measurement command into the buffer, such as ‘fM!’, and click Execute. Note that in this example, the address of the instrument has been changed from ‘0’ to ‘f’.
Figure 4. Initiate Measurement command
The initiate measurement command responds with the sensor address, the time until one or more measurements will be ready, and the number of measurements that it will make (actual measurement data is not returned). To retrieve the measurement data, employ the Send Data Command, as described by the SDI-12 protocol.
Figure 5. Send Data command
This command will return data from the sensor in the syntax format defined by the SDI-12 protocol, as seen below. The sensor responds with its address, followed by three measurement parameters.
Figure 6. Measurement data returned by SDI-12 device
Measurement & Automation Explorer provides a quick and easy way to obtain measurements from your SDI-12 devices. However, MAX is not customizable and introduces a ceiling of functionality in your data acquisition application. It also requires constant user operation and attention. By migrating to LabVIEW, we are able to create a user-defined application and leverage the power of the SDI-12 API to create an automated solution to your data acquisition needs.
3. Acquiring Data from LabVIEW
For more information about the NI LabVIEW graphical programming environment or to download an evaluation copy of the software, visit www.ni.com/labview.
To begin acquiring data from your SDI-12 device using LabVIEW, first make sure you have your system setup and the API installed according to the SDI-12 Communication System Whitepaper. Once installed, open LabVIEW and click on Find Examples… on the Getting Started screen. This brings up the NI Example Finder, in which you can perform a search for “SDI” and find the SDI-12 Multiple Operations shipping example. Open this example by double-clicking on the VI in the list box. The front panel of the example is illustrated in Figure 7.
Figure 7. SDI-12 Multiple Operations shipping example
The example has several tabs corresponding to the different actions that you can perform with your SDI-12 instruments. Each tab has associated code that sends SDI-12 commands to the instrument and parses the data that is returned. Investigate the Block Diagram to see how the LabVIEW SDI-12 API is used in this example and what commands are sent to perform each operation. You can use this example as a template to create your own SDI-12 communication or control program (remember not to save over the shipping example).
Address and Identification Information
The SDI-12 Multiple Operations example can be used for configuring your SDI-12 instruments as well as taking measurements. To begin the configuration of your instrument, first select the RS-232 port that your converter and sensor are connected to (RS232 Port In), and enter the address of the sensor you would like to communicate with (Sensor Address In). Run the VI with the Acknowledge Active tab selected to ensure that the sensor is active and operational. The response is a Boolean indicator that turns on when the sensor is active.
To query the address of your device, select the Address Query tab and run the VI. The Query Response Boolean will indicate a successful retrieval and the address will be displayed in the indicator. To change the address of your sensor, select the Change Address tab and specify the new address for your device in the New Address In control, then run the VI.
To display your sensor’s identification information, select the Send Identification tab and run the VI, making sure the correct RS-232 port and Sensor Address have been specified. The information for your sensor will be displayed on the front panel.
Figure 8. Retrieving sensor information
Reading Measurement Data
After configuring your SDI-12 instrument, use the Read Single and Read Multiple tabs to acquire data from the SDI-12 sensor(s) of your choice. To perform a single measurement, select the Read Single tab and fill in the controls accordingly. Run the VI to retrieve the measurement data from your device. The Read Single tab and descriptions of each front panel control and indicator can be found below.
Figure 9. Acquiring measurement data
Measurement Type In
Normal: In this mode, the controller sends an initiate measurement command to the sensor, and waits for the sensor to reply with an acknowledgement. After the acknowledgement is received, the controller fetches the measurement data from the sensor.
Continuous: In this mode, the sensor continuously acquires data, and the controller only generates fetch commands.
Concurrent: For concurrent measurements, the controller sends the initiate measurement command and waits a specified amount of time before fetching data from the sensors. This mode allows you to initiate measurements for multiple devices, instead of waiting for each device to send an acknowledgement.
Refer to the SDI-12 Protocol Specifications for more information on these measurement types.
Some sensors take more than one type of measurement. Depending on the sensor specifications, these measurements can be sent back to the controller in a single message or multiple messages. If the measurements are contained in multiple messages, this input specifies which set of measurements are displayed in the Measurements Out array indicator. There can be up to nine additional messages that contain the remaining measurements. For example, if working with the Campbell Scientific CS215-L Temperature and Relative Humidity sensor, both temperature and relative humidity measurements are returned in a single message, so “0” is the only valid input to this control. Consult the manual for your SDI-12 sensor for more information on how multiple measurement parameters are sent to the controller.
Set this Boolean control to true if you wish to perform a checksum on the response from the instrument.
Specifies the address of the SDI-12 instrument
Measurement Type Out
Signifies what type of measurement was performed
Reflects the Parameter In input that was specified by the user.
If the CRC Boolean control was set to true, this Boolean will read true, and a checksum will be performed on the data returned from the sensor. If this checksum fails, this indicator will still read true, but an error message will be displayed in the Error Out cluster.
Number of Measurements Out
This indicator signifies the number of measurements returned by the sensor. For example, when working with the Campbell Scientific CS215-L Temperature and Relative Humidity sensor, each initiate measurement command will return two measurements, corresponding to temperature and relative humidity. Consult the manual for your SDI-12 instrument for more information on the number of measurements the sensor can acquire.
This array contains the actual data acquired from the sensor. Again, consult your instrument’s manual to determine the order in which measurements are returned. In the screenshot above, the first element in the array corresponds to temperature, and the second element corresponds to relative humidity.
To take multiple measurements, select the Read Multiple tab. You can use this to take multiple measurements from the same instrument, or multiple measurements from multiple sensors. The combined settings of each array at a single index value correspond to the settings of a single measurement.
4. More Information on Environmental Monitoring
The LabVIEW SDI-12 API allows users to easily communicate with any SDI-12 instrument and instantly turn any computer or other device with a RS-232 port into a SDI-12 communication interface. This example demonstrates a subset of the functionality provided by the LabVIEW SDI-12 API. The API can be incorporated into any existing LabVIEW program or used as the foundation for a new environmental monitoring or control system. For more information on environmental monitoring and other green applications of National Instruments products, consult the Green Engineering homepage.