ioBridge Wiki api

Data Feed API

Sun, 24 Jan 2010 12:44:34 -0400

Data Feed API

For the ioBridge IO-204 Monitor and Control Module

Introduction

Each module that you have linked and registered to your account has a unique Feed URL. When requested, the URL returns a JSON or XML formatted snapshot of your module’s input and output states as well as any META information you have supplied such as Location, Latitude, Longitude, Labeling, and Scaling. The returned data allows for the creation of data logging, charting, custom scaling, mash-ups, and importing into server and client-side scripting. The API is lightweight and allows you to easily extend the ioBridge system data to remote systems, servers, clients, desktops, and applications.

The Feed URL is linked on your Module List under the Actions heading.

We are excited to see how you will extend the data from your module to your applications and services. Visit www.iobridge.net/projects for ideas and to submit your own ideas, comments, and project developments.

Extending the API

You may extend the data to server-side scripts, desktop applications, and client-side browser-based applications.

Here are some ways you can extend the API into your application:

Google Gadgets and Desktop Widgets
Windows and Mac Widgets
Custom Analog Sensor Scaling
Data Charting
Data Logging
Google Maps
Weather Widgets

Limitations

The feed requests are cached for 10 seconds, which means your application will only return new data every 10 seconds. ioBridge acts a proxy between the world and your module, so you don’t have to worry about your project going viral. We will only link to your module once every 10 seconds regardless of the number of people viewing your application, widget, or website based on the Data Feed API.

Server-side JSON

You can safely request your Feed URL from any server-side scripting language like Perl, Python, or PHP that supports JSON. The Feed URL returns the HTTP header of “Content-type: application/json”.

JSON Feed URL Example

http://www.iobridge.com/api/feed/key=0BosKdymNbB3LyiFYUVI

JSON Object

{
"module": {
      	"serial": "24000XXX",
            "label": "ioServer Monitor",
            "lat": "",
            "long": "",
            "location": "Gainesville, FL",
            "datetime": "Dec-24-2008 00:35:22 AM",
            "status": "Online",
            "channels": [
{"channel": "1", "label": "Channel 1", "AnalogInput": "384", "AnalogInputRaw": "384", "AnalogInputScale": "Raw", "DigitalInput": "Off", "DigitalInputState": "0", "DigitalOutput": "On", "DigitalOutputState": "1"},
{"channel": "2", "label": "Channel 2", "AnalogInput": "308", "AnalogInputRaw": "308", "AnalogInputScale": "Raw", "DigitalInput": "Off", "DigitalInputState": "0", "DigitalOutput": "Off", "DigitalOutputState": "0"},
{"channel": "3", "label": "Channel 3", "AnalogInput": "0", "AnalogInputRaw": "0", "AnalogInputScale": "Raw", "DigitalInput": "0", "DigitalInputState": "0", "DigitalOutput": "0", "DigitalOutputState": "0"},
{"channel": "4", "label": "Channel 4", "AnalogInput": "2.737", "AnalogInputRaw": "560", "AnalogInputScale": "Voltage", "DigitalInput": "Off", "DigitalInputState": "0", "DigitalOutput": "Down", "DigitalOutputState": "0"}
                        ]
        }
}

Server-side XML

By adding the format parameter to the Data Feed URL, you can alternatively format the results in XML.

XML Feed URL Example

http://www.iobridge.com/api/feed/key=0BosKdymNbB3LyiFYUVI&format=xml

XML Object

<?xml version="1.0"?>
        <module>
            <serial>2400XXXX</serial>
            <label>ioServer Monitor</label>
            <lat></lat>
            <long></long>
            <location>Gainesville, FL</location>
            <datetime>2009-07-03 02:20:36</datetime>
            <status>Online</status>
            <channel_1>
        		<label>Channel 1</label>
        		<AnalogInput>2.737</AnalogInput>
        		<AnalogInputRaw>14</AnalogInputRaw>
        		<AnalogInputScale>Voltage</AnalogInputScale>
        		<DigitalInput>On</DigitalInput>
        		<DigitalInputState>1</DigitalInputState>
        		<DigitalOutput>Off</DigitalOutput>
        		<DigitalOutputState>0</DigitalOutputState>
    	    </channel_1>
            <channel_2>
        		<label>Channel 2</label>
        		<AnalogInput>310</AnalogInput>
        		<AnalogInputRaw>310</AnalogInputRaw>
        		<AnalogInputScale>Raw</AnalogInputScale>
        		<DigitalInput>On</DigitalInput>
        		<DigitalInputState>1</DigitalInputState>
        		<DigitalOutput>Off</DigitalOutput>
        		<DigitalOutputState>0</DigitalOutputState>
    	    </channel_2>
            <channel_3>
        		<label>Channel 3</label>
        		<AnalogInput>256</AnalogInput>
        		<AnalogInputRaw>256</AnalogInputRaw>
        		<AnalogInputScale>Raw</AnalogInputScale>
 
        		<DigitalInput>On</DigitalInput>
        		<DigitalInputState>1</DigitalInputState>
        		<DigitalOutput>Off</DigitalOutput>
        		<DigitalOutputState>0</DigitalOutputState>
    	    </channel_3>
            <channel_4>
        		<label>Channel 4</label>
        		<AnalogInput>279</AnalogInput>
        		<AnalogInputRaw>279</AnalogInputRaw>
        		<AnalogInputScale>Raw</AnalogInputScale>
        		<DigitalInput>On</DigitalInput>
        		<DigitalInputState>1</DigitalInputState>
        		<DigitalOutput>Off</DigitalOutput>
        		<DigitalOutputState>0</DigitalOutputState>
            </channel_4>
</module>

Client-side JSON

If you are using jQuery or other client-scripting libraries to parse JSON, you have the ability to use JSONP (JSON with Padding) to get JSON from two different domains using Callback.

JSONP Callback Data Feed URL

http://www.iobridge.com/api/feed/key=0BosKdymNbB3LyiFYUVI&callback=?

When callback is used, the Feed URL returns a JSONP object.

JSONP Object

jsonp1230097032945({
        "module": {
            "serial": "24000XXX",
            "label": "ioServer Monitor",
            "lat": "",
            "long": "",
            "location": "Gainesville, FL",
            "datetime": "Dec-24-2008 00:36:40 AM",
            "status": "Online",
            "channels": [
{"channel": "1", "label": "Temperature", "AnalogInput": "103.6", "AnalogInputRaw": "665"
, "AnalogInputScale": "Temp F", "DigitalInput": "On", "DigitalInputState": "1", "DigitalOutput": "Off", "DigitalOutputState": "0"},
{"channel": "2", "label": "Channel Tester", "AnalogInput": "337", "AnalogInputRaw": "337", "AnalogInputScale": "Raw", "DigitalInput": "Hi", "DigitalInputState": "1", "DigitalOutput": "Off", "DigitalOutputState": "0"},
{"channel": "3", "label": "Servo", "AnalogInput": "269", "AnalogInputRaw": "269", "AnalogInputScale": "Raw", "DigitalInput": "On", "DigitalInputState": "1", "DigitalOutput": "On", "DigitalOutputState": "1"},
{"channel": "4", "label": "IR", "AnalogInput": "0", "AnalogInputRaw": "0", "AnalogInputScale": "Raw", "DigitalInput": "0", "DigitalInputState": "0", "DigitalOutput": "0", "DigitalOutputState": "0"}
                        ]
        }
})

Keys and Meta Information

You set the keys and meta information on the Modules tab. Data and configuration entered on the Modules tab are the returned labels and scaling in the XML/JSON object. Only I/O and Serial Channel modes return data in the feed.

The following keys are available to parse in your feed:

serial

Module Serial Number

label

Entered Module Label

lat

Entered Latitude (Decimal Degrees)

long

Entered Longitude (Decimal Degrees)

location

Entered Location Description

datetime

Date and Time of Module Snapshot

status

Status of Module (Offline, Online)

channel

Channel Number

label

Entered Channel Label

AnalogInput

Scaled Analog Input value (Voltage, Raw, Temperature)

AnalogInputRaw

Relative Analog Input Value (0-1023)

AnalogInputScale

Selected Scale of Analog Input

DigitalInput

Labeled Digital Input State

DigitalInputState

Digital Input State (1,0)

PulseCountRaw

Raw Onboard Pulse Count (Firmware C4 or above)

DigitalOutput

Labeled Digital Output State

DigitalOutputState

Digital Output State (1,0)

LastSerialInput

Last Serial Data Received by Serial Smart Board (Firmware C3 or above)

LastSerialOutput

Last Serial Data Sent by Serial Smart Board (Firmware C3 or above)

Parsing JSON

You can get access to any of the data in the JSON Object by parsing out the desired keys.

For example here is a jQuery request and data selection from feed:

function checkTemp() {
	
	$.getJSON("http://www.iobridge.com/interface/feed/FD_0BosKdymNbB3LyiFYUVI&callback=?",
	function (data) {
        storeTemp(data.module.channels[0].AnalogInput); updateGraph();
	});
		
}

“data.module.channels[0].AnalogInput “ references the scaled analog input value on channel 1 of the IO-204 Module.

If you would want the modules serial number, the reference would be “data.module.serial” using the serial key under module.

Client-side Application Step-by-Step

From soup to nuts, we wanted to show you a complete application extension of the Data Feed API and the steps involved. Share your projects at www.iobridge.com/projects.

The following projects takes your Feed URL extracts the Scaled Analog Input from Channel 1 and feeds Google Charts to return a Google-o-Meter indicating the current temperature using jQuery.

Step 1: Create a new HTML file called ServerTempNeedle.html

Step 2: Create the HTML frame work – head and body

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html> 
<head> 
<title>ioBridge Server Temperature</title> 
</head> 
<body> 
<div id="container"> 
	<div id="data_graph"></div> 
</div> 
</body> 
</html>

Step 3: Load jQuery from Google JSAPI to the document header

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

Step 4: Add a ready function when the HTML fully loads to check the temperature from the feed and set a timer that will check the temperature every 10 seconds

$(document).ready(function() {
	checkTemp(); // Gets initial temperature
	setInterval("checkTemp()", 10000); // Sets a 10 Second timer
});

Step 5: Add function that checks the temperature and updates the graph when the data is returned (use your feed URL to get your data or use our public feed to get our server temperature)

function checkTemp() {
	$.getJSON("http://www.iobridge.com/api/feed/key=0BosKdymNbB3LyiFYUVI&callback=?",
	function (data) {
 
			// Channel 1 is the first element in the array
			updateGraph(data.module.channels[0].AnalogInput);	
 
	});
}

Step 6: Add function to get the Google chart and display it in the “data_graph” division in the document body

function updateGraph(temp) {
 
	var newTemp = temp-50;
	newTemp = 100 - newTemp;
 
	var chart_url = "http://chart.apis.google.com/chart?"
	var chart_type = "cht=gom";
    	var chart_size = "&chs=300x200";
	var chart_title = "&chtt=ioBridge Server Temperature";
	var chart_data = "&chd=t:" + newTemp + "&chl=" + temp + " F";
	var url = chart_url + chart_type + chart_size + chart_title + chart_data;
 
	var i = $("<img>").attr("src", url);
	$("#data_graph").empty().append(i);
}

Step 7: Save file and open in web browser such as Safari, Chrome, Firefox, Opera, or Internet Explorer

Live Examples

Google Chart - Temperature Meter Source Code

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html> 
<head> 
<title>ioBridge Server Temperature</title> 
 
<script type="text/javascript" src="http://www.google.com/jsapi"></script> 
<script type="text/javascript"> 
    google.load("jquery", "1");
</script> 
<script type="text/javascript"> 
 
function updateGraph(temp) {
 
	var newTemp = temp-50;
	newTemp = 100 - newTemp;
 
	var chart_url = "http://chart.apis.google.com/chart?"
	var chart_type = "cht=gom";
    	var chart_size = "&chs=300x200";
	var chart_title = "&chtt=ioBridge Server Temperature";
	var chart_data = "&chd=t:" + newTemp + "&chl=" + temp + " F";
	var url = chart_url + chart_type + chart_size + chart_title + chart_data;
 
	var i = $("<img>").attr("src", url);
	$("#data_graph").empty().append(i);
}
 
function checkTemp() {
	$.getJSON("http://www.iobridge.com/api/feed/key=0BosKdymNbB3LyiFYUVI&callback=?",
	function (data) {
  	    updateGraph(data.module.channels[0].AnalogInput);
	});
}
 
$(document).ready(function() {
	checkTemp(); // Gets initial temperature
	setInterval("checkTemp()", 10000); // Sets a 10 Second timer
});
 
</script> 
</head> 
<body> 
 
<div id="container"> 
<div id="data_graph"> </div> 
</div> 
</body> 
</html>

Google Chart - Temperature Chart Source Code

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 
 
<html xmlns="http://www.w3.org/1999/xhtml"> 
 
<head> 
<title>ioBridge Server Temperature</title> 
 
<script type="text/javascript" src="https://www.google.com/jsapi"></script> 
<script type="text/javascript"> 
  google.load("jquery", "1");
  google.load("feeds", "1");
</script> 
 
<script type="text/javascript"> 
 
// Globals
var SecondsToSpan = 3600;  //Max of 6400
var PointsToKeep;
var sOffset = 0;
var UpperLimit;
 
function InitiateChart(){ 
 
   PointsToKeep = SecondsToSpan / 10;  // number of data point to keep in the plot 
 
   my_state.values = [];
 
   checkTemp();
 
   // call for a new data point every 10 seconds
   setInterval('checkTemp()',10000);
 
}
 
function my_state() { }
 
// This function puts the data into the Array
function storeValue(DataPoint) {
 
    // Update Page
    $("#currentTemp").text(DataPoint);
 
   DataPoint = Math.round(DataPoint);
 
   my_state.values.push(DataPoint);
 
   // If the plot has been open longer than SecondsToSpan then remove the first data point		
   if (my_state.values.length > PointsToKeep) {     
 
      my_state.values.splice(0,1);
      sOffset = sOffset + 10; 
   }
}
 
function reScale() {
 
  UpperLimit = 0;
 
  // Find the max value in the array
  for (var i = 0; i < my_state.values.length; i++ ) {
      if (my_state.values[i] > UpperLimit){
         UpperLimit = my_state.values[i] * 1.05;
      }
   }
}
 
// Encode the data for google charts
function ioEncode( valueArray ) {
 
   var chartData = [];
 
      for (var i = 0; i < my_state.values.length; i++) {
 
         var currentValue = my_state.values[i] * 100 / UpperLimit;
	     currentValue = Math.round(currentValue);
 
         chartData.push(currentValue);	
      }
 
   var stringTemp = chartData.join(',');
   var newString = "t:" + stringTemp;
   return newString;
}
 
function checkTemp() {
 
	$.getJSON("http://www.iobridge.com/api/feed/key=0BosKdymNbB3LyiFYUVI&callback=?",
	function (data) {
        storeValue(data.module.channels[0].AnalogInput); reScale(); updateGraph();
	});
 
}
 
// This function takes care of formating the URL for google charts and updating the image
function updateGraph() {
 
   var chart_url = "http://chart.apis.google.com/chart?"
   var chart_type = "cht=lc";
   var chartSec = my_state.values.length - 1;  	
 
   chartSec = chartSec * 10 + sOffset;
 
   var chart_size = "&chs=400x350&chtt=ioBridge Server Temperature&chds=0,100&chxt=x,y,x,y&chxl=2:||Time (s)||3:|||Temp||&chxr=1,0," + UpperLimit + "|0," + sOffset + "," + chartSec;
   var chart_data = "&chd=" + ioEncode(my_state.values);
   var url = chart_url + chart_type + chart_size + chart_data;
 
   var i = $("<img>").attr("src", url);
   $("#data_graph").empty().append(i);
 
}
 
</script>  
</head> 
 
<body onload="InitiateChart()"> 
<div id="container"> 
    <div id="data_graph"> </div>
 
    <p>&nbsp;</p>
 
    <div id="header"> 
	    Current Temperature is <span id="currentTemp"></span>&deg;F<br><br>
	    This chart will automatically add another data point every 10 seconds.   
    </div> 
</div>
</body> 
</html>

Additional Resources

JavaScript Widget Control API

Thu, 02 Jul 2009 23:40:32 -0400

JavaScript Widget Control API

To get access to the JavaScript Widget Control API, create a widget, note the widgetID, and embed the widget in the body of your web page.

Embed Code

Drop the widget Embed Code into your website and the ioBridge JavaScript Library is appended to the header of your page and gives you access to special ioBridge commands to control your widgets.

Example Widget Embed Code

<script type="text/javascript">
document.write(unescape("%3Cscript src='" + "http://www.iobridge.com/widgets/io.js?Q6Vs3RepsH6I' type='text/javascript'%3E%3C/script%3E"));
</script>

Hide Widget Code

If you don't need to see the actual widget, you can hide it using the following commands. It's recommend to embed hidden widgets near or right befire the </body> html tag.

<div id="ioWidgets" style="display:none;">
 
<script type="text/javascript">
document.write(unescape("%3Cscript src='" + "http://www.iobridge.com/widgets/io.js?Q6Vs3RepsH6I' type='text/javascript'%3E%3C/script%3E"));
</script>
 
</div>

widgetID

The widgetID is the string at the end of the widget code:

http://www.iobridge.com/widgets/io.js?Q6Vs3RepsH6I

Q6Vs3RepsH6I is the widgetID for the above widget.

JavaScript Commands

widgetExecute

Use widgetExecute on widgets that have one, fixed action. For example, if you created a fixed position servo widget that when normally clicked it sets a servo to a fixed position. Running widgetExecute from JavaScript allows JavaScript to execute the widget. The widget reacts just like if a user clicked on the widget.

widgetExecute('Q6Vs3RepsH6I');

widgetSetState

If the widget has two states, like On and Off buttons on an X10 widget or a toggle button, use the widsetSetState JavaScript command.

On:

widgetSetState('Q6Vs3RepsH6I',1);

Off:

widgetSetState('Q6Vs3RepsH6I',0);

widgetSetString

Variable serial and servo widgets need to use widgetSetString to send data to your module.

widgetSetString('Q6Vs3RepsH6I','This is my serial message');

widgetGetValue

If you have a widget that reads in the value of a digital input or analog input, you can get the that value by using widgetGetValue from JavaScript.

var myTemperature = widgetGetValue('Q6Vs3RepsH6I');

widgetGetString

If you have a variable message widget, you can get the current string by using widgetGetString from JavaScript. Use for variable servo position widgets and serial messages.

var servoPosition = widgetGetString('Q6V123epsH6I');

Special Characters

If you want to send special characters and bytes with widgetSetString, use the URL encoded characters.

For example, if you wanted to break a message into two lines with a carriage and linefeed, issue this JavaScript command:

widgetSetString('Q6Vs3RepsH6I','This is line 1.%0D%0AThis is line 2.');

The result will be:

This is line 1.

This is line 2.

%0D = carriage return

%0A = linefeed

Here is a table that lists all of the URL codes:

URL Codes

Example Application

iTurn - Servo Widget Control

Module API

Wed, 04 Mar 2009 22:11:34 -0400

Module API

The Module API is under development with limited private testing. There is not a scheduled public release date at the moment.

The new API will allow permissions-based, full control and monitoring of the module from JavaScript, PHP, Perl, Python, Java, and supporting a wide-range of web-applications and desktop application.

PHP Widget Control API

Thu, 09 Jul 2009 04:02:01 -0400

PHP Widget Control API

The PHP Widget Control API is a PHP script that resides on your own server. All you have to do is place the source code into a file named iobridge-proxy.php and call it from your own scripts and applications. The script acts as a proxy between your applications and the ioBridge widgets. You can use this script from anything that can GET a URL including same-site AJAX scripts, JavaScript, VisualBasic, Desktop Widgets, Python, PHP, Perl, etc.

Widget Types

All widget types are supported. If a widget returns a value, the values are also passed through the API.

Single Action

A widget that has a single button and when it's pressed executes a single action falls into this category. All you have to do is pass the widgetID or the widget label to execute these widgets through the API.

Variable

Widgets that require a parameter to execute are variable widgets. You have to send the widgetID or label and the value in the URL. Works for variable pulse widgets, servo widgets, and serial widgets.

On/Off

Some widgets have On/Off states. To execute the Off state pass the widget ID and the state 0. To execute the On state pass the widgetID and the state of 1. If you use the widget label method, you will have to get the URL for both states and hard code them into the switch/case section of the script. Use these settings for controlling digital outputs and X10 widgets.

Monitor

If you want to get the state of an digital output / input or analog input, pass the widgetID or label and the script returns the scaled or labeled values. The scale is dependent on what the widget has been set to.

widgetID

Before you get started, create widgets using the ioBridge Interface and note their widgetIDs. We will use these IDs with the API to control or access the associated widget.

Step-by-Step

Create a file named iobridge-proxy.php and copy the API source code into it

Upload the new file to your server

Access the script using GET statements by passing parameters into the URL

Parameters

Some parameters are required to use the API.

You can either send a widgetID or a widget label to control widgets. Using a widgetID is a little slower than hard setting the widget URLs with a widget label.

widgetID Method

http://your-server.com/iobridge-proxy.php?widgetID=XXXXXXXXXX&value=2000

Widget Label Method

http://your-server.com/iobridge-proxy.php?widget=servo&value=2000

Parameters

Parameter	Usage
widgetID	WidgetID or your widget
widget	Case Label for quick access to associated widget
value	Pass a variable widget a value, like setting a servo position
state	Set to 0 for the Off state and 1 for the On state of an Output Control Widget
debug	Set to display widget URL, requires widgetID to also be passed

widgetUrl

If you choose to use the Widget Label method, you will have to obtain the widget URLs for each of your widgets. The URL is easy to obtain with the Proxy Script. This method is a bit more complex, but when it's all setup you gain 30-40% faster and the URLs will be easier to understand.

To get the URL that is associated widget, pass the widgetID and set the debug parameters from a web browser.

http://your-server.com/iobridge-proxy.php?widgetID=XXXXXXXXXX&debug=1

Returns:

http://www.iobridge.com/interface/?actionID=RM_XXXXXXXXXXXX&sessionID=XXXXXXXXXXXXXXXXXXXX

The returned URL is a snap shot of the widget with the current settings. The URL is valid as long as it is being used regularly - sessionIDs expire with inactivity. If you make changes to the widget, you will have to obtain a new widget URL.

Once you have a valid widget URL you can hard code it to the Switch/Case section of the script, tag it with a label, and access it from the proxy by its label. We recommend adding a comment to the PHP script that has the orgignal widgetID so you can easily find it for later use.

PHP Proxy Source Code

<?php
/**
*	ioBridge Proxy that forwards calls to your ioBridge widgets
*
*	@version 1.1 July 3, 2009 - Added URL debug and "widget" select case by ioBridge Support
*	@version 1.0 June 21, 2009 - Original version Marc Fonteijn <marcfonteijn[ at ]gmail.com>
*
*	@link http://www.iobridge.net/forum/index.php/topic,447.0.html Comments & suggestions
*	@license http://creativecommons.org/licenses/GPL/2.0/ Released under a Creative Commons GNU GPL License
*/
  $widgetID = $_GET['widgetID'];
  $widget =  $_GET['widget'];
  $state = $_GET['state'];
  $value = $_GET['value'];
  $debug = $_GET['debug'];
 
  $value = urldecode($value);
 
  if ($widgetID) {
 
      $url = "http://www.iobridge.com/interface/?actionID=RM_Widget&widgetID=" . $widgetID . "&dt=" . time();
      $ch = curl_init($url);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, '1');
      $response = curl_exec($ch);
      curl_close($ch);
 
      $start = strpos($response, "www.iobridge.com/interface/?actionID=");
      if(isset($state) && $state == "0")
        $start = strpos($response, "www.iobridge.com/interface/?actionID=", $start + 1);
      $end =  strpos($response, ";", $start);
      $widgetUrl = "http://" . substr($response, $start, $end - $start - 4);
 
      if ($debug) {
 
         echo $widgetUrl;
         exit;
 
      }
  }
  else {
 
      switch ($widget) {
       case "toggle":
        $widgetUrl = "http://www.iobridge.com/interface/?actionID=RM_XXXXXXXXXXXX&sessionID=XXXXXXXXXXXXXXXXXXXX"; 
        break;
       case "analog":
        $widgetUrl = "http://www.iobridge.com/interface/?actionID=RM_XXXXXXXXXXXX&sessionID=XXXXXXXXXXXXXXXXXXXX"; 
        break;
       case "off":
        $widgetUrl = "http://www.iobridge.com/interface/?actionID=RM_XXXXXXXXXXXX&sessionID=XXXXXXXXXXXXXXXXXXXX"; 
        break;
       case "on":
        $widgetUrl = "http://www.iobridge.com/interface/?actionID=RM_XXXXXXXXXXXX&sessionID=XXXXXXXXXXXXXXXXXXXX"; 
        break;
       case "servo":
        $widgetUrl = "http://www.iobridge.com/interface/?actionID=RM_XXXXXXXXXXXX&sessionID=XXXXXXXXXXXXXXXXXXXX"; 
        break;
      }
  }
 
  if ($widgetUrl) {
 
      $widgetUrl .= "&setValue=" . urlencode($value);
 
      $ch = curl_init($widgetUrl);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, '1');
      $response = curl_exec($ch);
      $start = strpos($response, "=");
      $end =  strpos($response, ";", $start);
      echo substr($response, $start + 2, $end - $start - 3);
 
  }
?>

PHP Proxy without JavaScript

The PHP Proxy script is perfect for when you need to control the module without the use of JavaScript. Older mobile clients on a standard mobile phone can't process client side scripting, but they often support HTML.

You can use the proxy with links or HTML forms.

Links Example

<html> 
  <head> 
    <title>PHP Proxy with Links</title> 
  </head> 
  <body> 
    <a href="iobridge-proxy.php?widget=LED&value=Hello+World" target="iframe">Send Message to LCD</a> | 
    <a href="iobridge-proxy.php?widget=servo&value=1000" target="iframe">Servo Left</a> | 
    <a href="iobridge-proxy.php?widget=servo&value=2000" target="iframe">Servo Right</a>
    <iframe id="iframe" name="iframe" width="0" height="0" frameborder="0"></iframe>
  </body> 
</html>

HTML Form Example

<html> 
  <head> 
    <title>PHP Proxy with HTML Form</title> 
  </head> 
  <body> 
        <form action="http://your-server.com/iobridge-proxy.php" method="get" target="iframe"> 
          <textarea row="2" cols="16" id="value" name="value"></textarea><br /> 
          <input type="hidden" name="widget" value="serial" />          
          <input type="submit" value="Submit" />          
        </form> 
     <iframe id="iframe" name="iframe" width="0" height="0" frameborder="0"></iframe>
  </body> 
</html>

Resources

Sample Application to Control Serial LCD

Marc Fonteijn's Original ioBridge PHP Proxy API

JavaScript Widget Control API

Serial API

Mon, 08 Jun 2009 04:05:55 -0400

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 module/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 module 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 module 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 module/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 module/channel is placed in the buffer. Consequently, requests for serial data are served out of that buffer. This means that serial data from a module 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 module and channel combination. The API key is used in HTTP requests for serial data. Contact ioBridge support if you would like a serial API Key generated for you.

The Serial Data Object

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

serialObject.serial - module'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 you particular module and I/O channel.

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

Initial request is made to the serial API with the appropriate API key and streamID=new.
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 module. 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.
The script will make another request with the API key. The streamID will be set to the value returned in step 2.
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);
	});			
}
 
$(document).ready(function() {
 
	checkSerial();
 
});
 
</script> 
</head> 
<body> 
 
<div id="updateID">Listening...</div>
 
</body> 
</html>

Serial Web Services API

Sun, 18 Apr 2010 21:24:18 -0400

Serial Web Services API

The Serial Web Services API allows data sent into the Serial Smart Board (SB-5) and be routed to web services from Twitter, Google, Yahoo, etc. Using this API, you can have a microcontroller send email, request stock quotes, and get the current temperature and time - opening up the world wide web to microcontrollers and embedded serial devices. The IO-204 acts as a conduit to the Internet and web services for microcontrollers connected to a serial smart board.

Setup

Connect a serial device to the transmitter, receiver, and ground of the Serial Smart Board connected to the IO-204 Ethernet module. Match baud rate and signal type (true or inverted) on both your serial device and the serial smart board. Serial settings are configured on the Module tab.

Usage Limits

Transactions

Using this API allows for so many transactions in a 24 hour period. Abuse will cause the disruption of messages temporally. The limit is 1440 transaction is a 24 hour period, which equates to one transaction per minute.

Long Messages

The serial smart board has a buffer of 200B. When the buffer is full, the RTS pin goes high. The buffer clears a moment later and you can send more data. You can send long commands thru the board if you put a second of pacing between 200B chunks of the message. The API looks for the opening brackets and closing brackets before the service acts on the command. However, if you transmit more than 200B to the board without pacing, only 200B will be transmitted to the server which breaks the command.

Web Service Commands

The format for commands are as follows:

[[[command|parameters]]]

Sending serial strings wrapped in brackets will cause the command to be routed to web services. The commands are delimited by pipes (“|”).

email

[[[email|address|subject|body]]]

Reply: Sent

Use the email service to allow your microcontroller to send email, text messages, Twitter / Facebook updates, and UberNote notes

Text Messaging

You can also receive notifications to an event as a text message by entering your cell phone's email address. Your cell phone number can be converted to an email address based on your service provider.

AT&T: yournumber@txt.att.net
Verizon: yournumber@vtext.com
T-Mobile: yournumber@tmomail.net

Note: ioBridge Corporation is not responsible for charges incurred by text messaging. Your standard text messaging rates apply with your mobile carrier.

Twitter Mail

Twitter Mail allows you to send an email to a email address that's linked to your Twitter account. They will then use the Twitter API to post a new Twitter for you. The service works extremely well. Once you get your Twitter Mail address you can natively add it to your Email Accounts on ioBridge.

Twitter Mail

Social Networks via Ping.fm

Ping.fm allows you to update multiple social networks via email. Ping.fm is recommended to update your Twitter, Facebook, and GTalk status. Once you sign up at Ping.fm, you will have an email address that is linked to your social networks. Add that email account to your ioBridge.com account and now your ioBridge actions can tweet, update Facebook, etc.

Ping.fm

UberNote

UberNote is free note taking service that is a replacement for Google Notes. UberNote allows email access to post new notes. Once you setup and account, an email that is linked to your account is created and listed under your settings page. If your action sends a message to the UberMail address, it will be automatically posted to your account. UberNote also supports tagging and public RSS feeds of notes.

UberNote

datetime

[[[datetime]]]

Reply: yyyy-mm-dd hh:nn:ss (GMT/UTC)

date

[[[date]]]

Reply: yyyy-mm-dd

time

[[[time]]]

Reply: hh:nn:ss (GMT/UTC)

stock

[[[stock|symbol]]]

Reply: (last trade stock price)

weather

[[[weather|location|options]]]

Location can be any zip code or city name.

Options:

temp_f
temp_c
humidity
wind_condition
sunrise
sunset
rain

Default: temp_f

Reply: (weather info)

calc

[[[calc|expression]]]

Expressions are based off of Google Calculator syntax. You can convert units and perform mathematical operations.

Reply: (result)

get

[[[get|url]]]

Reply: (response up to the first 70-80 characters)

Use the “get command” to GET a URL of your choice.

data_log

[[[data_log|key|timestamp|data]]]

key: 18 alpha numeric characters - The key is created at ioBridge.com by adding a Data Log from an External Source to your account. This key will tie the serial data being pushed to the database.

timestamp: yyyy-mm-dd hh:nn:00 - If the timestamp field is blank, the API will use the current GMT/UTC system time.

data: Serial string up to 50 characters

Reply: Inserted

Arduino Example

Request

Serial.print("[[[stock|GOOG]]]");

Reply Handler

char charIn = 0;
byte i = 0;
char stringIn[32] = "";

while(Serial.available()) {
    charIn = Serial.read();
    stringIn[i] = charIn;
    i += 1;
}

int stockPrice = atoi(stringIn);

Basic Stamp (BS2) Example

Humidity

The following command replies back with the current humidity percentage in Gainesville, FL.

SEROUT 8,84,["[[[weather|Gainesville, FL|humidity]]]"]

Sends serial data out of pin 8 of a BS2 at a baud rate of 9600 with an inverted signal

Basic Stamp Email

The following command emails the current temperature measured by a serial temperature sensor.

SEROUT 8,16468,["[[[email|support@iobridge.com|My Temperature|My temperature in my room is ", SDEC tempF,".]]]"]

Sends serial data out of pin 8 of a BS2 at a buad rate of 9600 with a true signal - SDEC tempF is from a serial sensor hooked up to the BS2

Projects

Internet-enabled Message Center - Project from ioBridge user that uses the Arduino and the Serial Web Services API to get stock quotes, get weather, and send email.

Resources

Serial Smart Board (SB-5)

Web-enabled Arduino

Shell Script Widget Control API

Thu, 02 Jul 2009 23:35:32 -0400

Shell Script Widget Control API

This is a method of controlling widgets using URI requests only, and as such is amenable to being placed into Unix-like shell scripts.

URI Method summary

There is a two-step procedure to talk to a widget. You will need to know

the current time (in milliseconds from epoch; use the command “date +%s” from a GNU date or the result from the C function time() to get this time in seconds).
your widgetID. See JavaScript Widget Control API for how to obtain a widgetID.

The procedure is as follows.

Get a sessionID for your widget.
Send a message to your widget using the sessionID.

Getting a sessionID

Make a request for some JavaScript code using this URI:

https://www.iobridge.com/interface/?actionID=RM_Widget&widgetID=XXXXXXXX&dt=NNNNNNNNN

Substitute XXXXXXXX with your widgetID and NNNNNNNN with the time in base 10.

The server responds with a block of JavaScript which contains the sessionID. The code is somewhat tricky, and may change, but the data we need is in the first argument to the JavaScript function DI(). This argument is a URI enclosed by URL-encoded quotes. This URI contains the sessionID, but the whole URI can be used as as stem for sending an action to the widget, and will be called AAAAAAAA.

Using the action base URI to activate a widget

This is fairly simple. Suppose your widget takes a value (e.g., serial send widget, or servo variable position); then make a request with this URI:

AAAAAAAA&setValue=MMMMMMMM&dt=NNNNNNNN

Substitute AAAAAAAA with the action base URI found above (it has the sessionID and widgetID encoded into it). Substitute MMMMMMMM with the value to send to the widget in text. (It's a good idea to URL-encode it if you're not sanitizing the inputs.) Again, NNNNNNNN is the current time.

Example bash script

There is some sample code. Replace the widgetIDs marked in the function parsewidget() with your own. This script has been tested with a Serial LCD (FB-7) and Servo Controller Smart Board (SB-1). modules.

This script requires the external commands “date”, “wget” and “hexdump”. They are fairly common on most Unix/Linux/BSD systems.

#!/bin/bash
# Daniel F. Smith, iobridge@dfsmith.net
#
# Usage:
#    iobridge.sh <widget> message [message...]
#
# The <widget> argument can be the widgetID or a friendly name
# (see the parsewidget function).  If the friendly name starts   
# with "lcd", then some convenient substitutions will be made
# to the message (see the parsemessage function).
#
# E.g.,
#    ./iobridge.sh lcd '%clear%Hello world!'
#    ./iobridge.sh servo 400 2000 400
#    ./iobridge.sh wuQRD6ENmrDq 1000
 
WGET=/usr/bin/wget
HEXDUMP=/usr/bin/hexdump
DATE=/bin/date
 
function gethttp {
   $WGET -qO- "$1"
}
 
function urlencode {
   r=`echo -n "$1" | $HEXDUMP -ve '/1 " %02X"'`
   echo "${r// /%}"
}
 
function stripquote {
   x="$1"
   x=${x/#\&\#39;/}
   x=${x/%\&\#39;/}
   echo $x
}
 
function getTime {
   echo $(( $SECONDS * 1000 ))
}
 
function getactionbaseurl {
   widget="$1"
 
   rmbaseurl="https://www.iobridge.com/interface/?actionID=RM_Widget"
   rmurl="${rmbaseurl}&widgetID=${widget}&dt=`getTime`"
   rmdata=`gethttp "$rmurl"`
 
   diargs="${rmdata/*DI\(/}"
   diargs="${diargs/\)*/}"
   diarg1=`stripquote "${diargs/,*/}"`
   echo "$diarg1"
}
 
function parsewidget {
   case "$1" in
   lcd)
      echo "Aj4OEj3OSzDw" # dfsmith's personal LCD widget
      ;;
   servo | servo1)
      echo "wuQRD6ENmrDq" # dfsmith's personal servo
      ;;
   *)
      echo "$1"
      ;;
   esac
}
 
function parsemessage {
   message="$2"
   case "$1" in
   lcd*)
      lcdesc=$'\xFE'
      message="${message//%escape%/${lcdesc}}"
      message="${message//%bright%/${lcdesc}B}" # "X" (0-9)
      message="${message//%delaybright%/${lcdesc}T}" # "XD" (0-9,binary delay)
      message="${message//%reset%/${lcdesc}Z}"
      message="${message//%clear%/${lcdesc}C}"
      message="${message//%home%/${lcdesc}H}"
      message="${message//%move%/${lcdesc}L}" # "RRCC" (row column)
      message="${message//%cursoroff%/${lcdesc}K}"
      message="${message//%cursoron%/${lcdesc}J}"
      message="${message//%cursorblink%/${lcdesc}P}"
      message="${message//%cursorsteady%/${lcdesc}Q}"
      message="${message//%scroll%/${lcdesc}S}" # "RS...\xFE" (row,speed)
      message="${message//%hbar%/${lcdesc}G}" # "RLLHHX" (row,L-label,R-label,a-k)
      message="${message//%vbar%/${lcdesc}V}" # "X" (0-8)
      ;;
   esac
   echo `urlencode "$message"`
}
 
SECONDS=`$DATE +%s`
 
logicalwidget="$1"; shift
widget=`parsewidget "$logicalwidget"`
 
actionbaseurl="`getactionbaseurl "$widget"`"
 
while [ "$1" != "" ]; do
   message="$1"; shift
   encodedmessage=`parsemessage "$logicalwidget" "$message"`
   actionurl="${actionbaseurl}&setValue=${encodedmessage}&dt=`getTime`"
   gethttp "$actionurl" >/dev/null
done

Static Widget API

Wed, 24 Mar 2010 17:42:39 -0400

Static Widget API

This API allows you to interact with your widgets via static HTTP POST/GET calls vs. dynamic scripting. This enables direct and open access to your widgets to support third-party desktop and mobile applications.

The API is simple enough for mobile phones to control and monitor widgets and robust enough to support LabVIEW applications.

Get the "widgetID"

A widget created on the ioBridge.com Interface created an embed tag for use on websites. To connect the API calls to the widget you will need the the “widgetID”.

API Access

To access the API, you can use GET or POST calls. You can also use “http” or “https” to send API calls.

HTTP GET

http://www.iobridge.com/widgets/static/id=[widgetID]

HTTP POST

http://www.iobridge.com/widgets/static/post
id=[widgetID]

Parameters

To send additional parameters to the API, use an ”&” as a delimiter for each parameter passed.

Here is an example:

http://www.iobridge.com/widgets/static/id=[widgetID]&value=1&format=xml

Here are the parameters that you can send to the API:

id

Required - widgetID of widget created on the ioBridge.com Interface

value

Optional - Value to be passed to the widget (URL encoded)

Logic High/On/1 - value=1
Logic Low/Off/0 - value=0

format

Optional - Type of format for the API response (Default is Text)

Text - format=text
HTML - format=html
WAP/WML - format=wml
XML - format=xml
VXML - format=vxml
JSON - format=json

<html> 
  <head> 
    <title>Static Widget API with HTML Form</title> 
  </head> 
  <body> 
        <form action="https://www.iobridge.com/widgets/static/post" method="post"> 
          <textarea row="2" cols="16" id="value" name="value"></textarea><br />
          <input type="hidden" name="id" value="ah0MtPBUZN5c" />       
          <input type="submit" value="Submit" />          
        </form> 
  </body> 
</html>

WAP/WML Page

This example is a WML formatted page to control a digital output using HTTP GET calls.

<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//WAPFORUM//DTD WML 2.0//EN"
    "http://www.wapforum.org/dtd/wml20.dtd">
 
<wml>
  <card title="Room Lights">
    <p><a href="http://www.iobridge.com/widgets/static/id=s3T4SXSOjH4X&value=1&format=wml">On</a></p>
    <p><a href="http://www.iobridge.com/widgets/static/id=s3T4SXSOjH4X&value=0&format=wml">Off</a></p>
  </card>
</wml>