Web services: hosting a Web service technical principles
Learn the technical principles necessary to host a Web service on the Academic RIO Device. Remote clients such as another LabVIEW-based target, an IoT device, or a conventional browser can retrieve sensor measurements and control indicators and actuators using commands obtained from the remote client's request query string.
Run this example Academic RIO Device Web service project to get an idea of what you can accomplish – this example serves the states of onboard sensors and system information to a remote client, and allows the remote client to control the onboard LEDs.
Technical principles
Fundamental concepts
A “Web service” uses the same infrastructure as the web, i.e., web servers and clients, HTTP, URLs, and so on, but is intended for machine-to-machine exchange of specific information.
LabVIEW VIs that implement web service behavior are located under the “Web Resources” virtual folder of the LabVIEW project. These VIs are known as “method” VIs. A method VI retrieves values from the URL query string (if needed and available), implements the behavior of the web service, e.g., performs a calculation, reads one or more sensors, captures an image, reads an onboard file, and so on, and finally generates the web page content to be delivered back to the client.
LabVIEW provides two techniques to retrieve URL query string values and to return web page content generated by the VI:
“Terminal” – The block diagram uses front-panel controls connected to the VI’s icon frame to retrieve query string values. The front-panel control name corresponds to the query string name. Similarly, the front-panel indicators generate the web page content as either plain text, HTML, JSON, or XML. This technique is quick and simple, but the output format is limited.
“Streaming” – The VI can return output under your complete control, and can also return non-text output such as images and audio. These VIs require a little more effort to implement because they require the following elements:
Web service request front-panel control (must be connected to a terminal on the icon connector),
One or more “Read Form Data” VIs to read the name/value pairs in the GET query string of the URL,
Block diagram code to process the web service request, possibly including data processing, calculations, file I/O, analog I/O, digital I/O, etc.
“Set HTTP Response MIME Type” VI to specify how the remote client is to interpret the response from the web service, e.g., plain text, HTML code, image file, JSON code, etc., and
“Write Response” to send the web service information (i.e., a “web page”) to the remote client.
Web services return structured information most often encoded as ASCII strings in XML (Extensible Markup Language) and JSON (JavaScript Object Notation; pronounced “JAY-suhn”). Use the LabVIEW function “Flatten To JSON” with the “streaming” output technique to accept a data cluster with named values to generate the JSON string. The cluster may include arrays and nested clusters with some limitations; see the help page for details.
Security issues – LabVIEW Web Services on the Academic RIO Device does not support SSL; keep this in mind if using passwords or API keys because they are not secured.
A LabVIEW Web service can also serve static web pages, for example, a default “index.html” page. See the excellent tutorials at http://www.w3schools.com to learn how to create HTML code.
The “interactive.html” page in the hands-on demo uses JavaScript to implement the interactive behavior, i.e., the page refreshes whenever you enter a new value for the LED hex code. See the NI Community tutorial Web Services Getting Started Series and in particular the page Exploring Update Methods to learn more.
LabVIEW implementation of a Web service client
The following step-by-step video tutorial shows you how to build from the ground up a Web service similar to the one demonstrated earlier. This example Web service includes endpoint URLs to report the system date and time as well as the values of onboard devices (accelerometer and pushbutton), to set the onboard LEDs to a desired pattern, and to retrieve a webcam image with the option of selecting its dimensions and automatically refreshing the image once every five seconds. The tutorial also illustrates how to use the basic terminal-based technique (use front-panel controls and indicators connected to the icon frame) to retrieve query values and to return text, HTML, and JSON strings, and the stream-based technique to take control of the exact appearance of returned text and to serve other types of content such as a JPEG image.
NOTE: A USB webcam is required for Steps 7 to 9.
NOTE: The embedded video previews all look the same, but the video will start at the correct place for each step.
Create the LabVIEW project framework: create a new Academic RIO Device project, add a new “Web Service” called “API”, and create “Web Resources” folders for external devices (webcam), onboard devices (accelerometer, LEDs, and pushbutton), and system information (time and date):
Create the “json/onboard/accelerometer” method VI. Use the “terminal” output method to return the three-axis accelerometer values as a JSON string in both cluster and array formats for the sake of comparison:
Refine the “external/webcam” method to cause the browser to automatically refresh the page (which requests a new image) every few seconds by setting the “Refresh” field to the HTTP header: