You are here: Home / ioBridge API / Serial API

Serial API

The most reliable way to get serial data from a Serial Smart Board programmatically is through the Serial API. Of course with the reliability comes a little complexity. A continuous serial stream differs greatly from the request/response model of HTTP. In order to deliver serial content, the serial API server uses long polling HTTP connections, API keys, and FIFO Buffer.

Long Polling HTTP

In a normal HTTP transaction, a request is made (from a browser or a server-side script) in the form of a GET. The server receives the GET request and immediately assembles the data for the reply. The data may be a static file or created dynamically. In either case, the data is sent back to the requester as soon as possible. The original requester then receives and processes the data and processes.

In a long polling HTTP, a request is again made with a GET command. Although, with a long polling request the server does not always immediately reply. The server may hang onto the connection for quite a while until some other even triggers a response to be sent to the waiting requester. Alternately, the connection may hang too long and the request will timeout.

The serial API uses long polling requests. Since serial data can arrive at serial API server at any time, it is beneficial to have a request already queued up in order to pass the serial data along with the least latency.

In general, the serial API works as follows. A script makes a request for serial data. The serial API server hangs onto that request until a chunk of serial data from a particular web gateway/channel is received or the connection times out. If data is received, it is passed on as the response to the request for data. If no data was received from the web gateway then an empty message is sent back as the response.

The Concept of Serial API FIFO Buffers

FIFO: First In First Out

In practice, a script requesting serial data will make requests over and over to the serial API. The script will make an initial request and upon receiving a reply, it will act on the data and make another request for more data. The only problem with this scenario is that it is possible for entire chunks of serial data to get lost. For example, suppose there is a request awaiting data on the server. Now, imagine two chunks of serial data are sent from the web gateway within milliseconds of each other. The first chunk of data will be used to fulfill the waiting request. By the time the originating script receives the first data chunk, processes it and issues another request, the second piece of serial data will have been lost. This is because the serial API server didn’t see any outstanding requests for serial data from this web gateway/channel.

To overcome this problem of lost messages, FIFO buffers are uses to ensure no serial data is lost between requests. Upon the first serial API request for data, a unique buffer is created and given a unique name. From that point on, serial data received from a particular web gateway/channel is placed in the buffer. Consequently, requests for serial data are served out of that buffer. This means that serial data from a web gateway will fill a buffer while requests for serial data will empty the buffer. This way no serial data is lost. A buffer will remain active as long as at least one request for data is made every 60 seconds. A request to the serial API server will timeout after 30 seconds and the server will respond with an emtpy message. In the case the originating script will just make another request. In 60 seconds elapse without a request for data from a particular buffer, the buffer will be deleted along with the data contained in it.

The Serial API Key

To provide a measure of security against unauthorized eavesdropping of your serial data, a lengthy alpha-numeric API key is used to access serial data. Each API key is set to a specific web gateway and channel combination. The API key is used in HTTP requests for serial data.

The Serial Data Object

The serial API server responds in the form of a JSON object. The ojects elements are as follows:

  • serialObject.serial – web gateway’s serial number
  • serialObject.channel – I/O channel of the serial board
  • serialObject.timedate – time stamp of when the data was sent
  • serialObject.streamID – streamID of the live buffer
  • serialObject.SerialData – the actual serial data

Sequence of Events for using the Serial API

First take care of the following steps.

  • Attach Serial Smart Board to an I/O channel and set the configuration settings (mode, baudrate).
  • Attach serial peripheral and check for proper data transmission with the serial widgets.
  • Attain a Serial API key for your particular web gateway and I/O channel.

Now for the general sequence of how the script requesting serial data should operate.

  1. Initial request is made to the serial API with the appropriate API key and streamID=new.
  2. Eventually, the serial API server will respond with a JSON object. The serialObject.SerialData element may be empty if no serial data was receive from the web gateway. The object will contain an alpha-numeric string assigned to serialObject.streamID. This is the unique identifier for the buffer that was created upon the initial request in step 1.
  3. The script will make another request with the API key. The streamID will be set to the value returned in step 2.
  4. Server will respond with a JSON object. The returned streamID element will be the same as in step 2. Go to step 3.

Example Code using jQuery

This example will make calls to the Serial API. On the initial call, a serial buffer will be created with a unique streamID. This same streamID is used on subsequent calls. If serial data is returned in the serialObject then it is shown in the updateID division.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 
<html> 
<head> 
<title>ioBridge Serial Buffer Stream</title> 

<script type="text/javascript" src="http://www.google.com/jsapi"></script>
<script type="text/javascript"> 
    google.load("jquery", "1");
    google.load("feeds", "1");
</script> 
<script type="text/javascript"> 

function checkSerial(returnedStreamID) {

	if (returnedStreamID) {}
	else {returnedStreamID = "new";}

	$.getJSON("http://www.iobridge.com/api/serial/buffer/key=FD_XXXXXXXXXXXXXXXXXXXX&streamID="+returnedStreamID+"&callback=?", function (data) {   

        	var SerialData = data.serialObject.SerialData;

		if (SerialData) {	
			document.getElementById('updateID').innerHTML = SerialData; 
		}	

		var streamID = data.serialObject.streamID;
        	checkSerial(streamID);
	});			
}

$(checkSerial);

</script> 
</head> 
<body> 

<div id="updateID">Listening...</div>

</body> 
</html>
Filed Under: Uncategorized