API

From MyRobots wiki
Jump to: navigation, search

Contents

Introduction

MyRobots.com Structure

MyRobots.com provide an Open Source API. You can use this to send and receive data with your robot.

OEMs

MyRobots is still in its beta phase but we expect to be ready soon to work with OEM and manufacturers in order to offer end-to-end solution to web-enable your robots and service. MyRobot provide low-cost hardware and software to connect your robots to Internet and reap the benefits. Here some ideas of the benefits for the OEM/Manufacturers point of view:

  • Monitor the robots in their real environment;
  • Offer better service to the customers (real time alerts, upgrades, apps, tips on maintenance etc.);
  • Get important statistics and information to improve the products and service;
  • Lower the cost of support, return and warranty;
  • Increase the number of registered customers;
  • Bring the community to develop robot apps for your robots;
  • Get a serious advantage on your competition and embrace the future of Cloud Robotics;
  • Have your own custom-branded interface offering web base services for your robots.

MyRobots will offer soon professional support to help integrate technology into your products. If you are interested in a strategic partnership with MyRobots, please contact us via the support centre.

No Web Access?

For robots without access to doing HTTP POSTs or GETs, see the Open Serial Protocol to learn about using a Serial-to Ethernet gateway, such as the MyRobots Connect and serial commands to communicate to MyRobots.com

Keywords

Here are some keywords that are used in the API. An understanding of the terms will make the API documentation easier to understand.

  • Channel or Robot - The name for where data can be inserted or retrieved within the ThingSpeak API, identified by a numerical Channel ID.
  • Field - One of eight specific locations for data inside of a channel, identified by a number between 1 and 8. It can store numeric data from sensors or alphanumeric strings from serial devices or RFID readers
  • Status - A short status message to augment the data stored in a channel
  • Location - The latitude, longitude, and elevation of where data is being sent from
  • Feed - The collective name for the data stored inside a channel, which may be any combination of field data, status updates, and location info
  • Write API Key – A 16 digit code that allows an application to write data to a channel
  • Read API Key – A 16 digit code that allows an application to read the data stored in a channel

Addresses and Locations

   Regular URL:
   http://bots.myrobots.com
   Secure URL:
   https://bots.myrobots.com
   IP Address:
   http://204.92.52.252
   Cross-domain XML:
   http://bots.myrobots.com/crossdomain.xml

Write API Key

In order to update a channel, you need to know your Write API Key, it is provided once you have registered your robot.

Robot ID

Every Robot has a unique Channel ID. The Channel ID number is used to identify the channel when your application reads data from the channel.

Private/Public Robots

By default, your Robot is public, which means its data will can be seen by any other user. You can make a Robot private by unchecking the "private check-box on the robot's profile which will encrypt the data that you can decipher with the Write API key.

API Rate Limit

The service via MyRobots.com has a rate limit of an update per channel every 30 seconds. This limit is so that the service can remain free and give everyone a high-level of service.

Caching

Caching is implemented on JSON and XML formats on feeds. Feeds that return more than 100 entries are cached for 5 minutes. This will allow great performance for popular applications. The Last API call and feeds that specify “results=100″ or less are not cached, so that you can produce real-time applications.

Updating a Channel

   Method: POST or GET
   Update URL:
   http://bots.myrobots.com/update


Required Parameter:

   key=[Write API Key]

Optional Field Parameters:

   field1=[Field 1 Data]
   field2=[Field 2 Data]
   field3=[Field 3 Data]
   field4=[Field 4 Data]
   field5=[Field 5 Data]
   field6=[Field 6 Data]
   field7=[Field 7 Data]
   field8=[Field 8 Data]

Optional Location Parameters:

   lat=[Latitude in decimal degrees]
   long=[Longitude in decimal degrees]
   elevation=[Elevation in meters]

Optional Status Parameter:

   status=[Status Update]

Example

This example sets field1 to 50 and Status to "Hello".

 http://bots.myrobots.com/update?key=PASTEYOURKEYHERE&field1=50&status=Hello

Reply:

If the update is successful, the API will respond with the entry_id of the update. If the response is “0″ then the update failed.

Feed Formats

Retrieving Robot Feeds

When retrieving data from a Robot feed, you may specify one of the following formats:

  • json
  • xml
  • csv
   Method: POST or GET
   Feed URL:
   http://bots.myrobots.com/channels/(robot_id)/feed.(format)

Optional Parameters:

  • key=[API Key] – no key required for public channels
  • results=[number of entries to retrieve (8000 max)]
  • days=[days from now to include in feed]
  • start=[start date] – YYYY-MM-DD%20HH:NN:SS
  • end=[end date] - YYYY-MM-DD%20HH:NN:SS
  • offset=[timezone offset in hours]
  • status=true (include status updates in feed)
  • location=true (include latitude, longitude, and elevation in feed)
  • min=[minimum value to include in response]
  • max=[maximum value to include in response]
  • round=x (round to x decimal places)
  • timescale=x (get first value in x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
  • sum=x (get sum of x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
  • average=x (get average of x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
  • median=x (get median of x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
  • callback=[function name] (used for JSONP cross-domain requests)

Examples:

http://bots.myrobots.com/channels/9/feed.json
http://bots.myrobots.com/channels/9/feed.json?median=10
http://bots.myrobots.com/channels/9/feed.json?start=2011-11-11%2010:10:10&end=2011-11-11%2011:11:11

Retrieving the Last Entry in Robot Feed

  Method: POST or GET
  Feed URL:
  http://bots.myrobots.com/channels/(channel_id)/feed/last.(format)

Optional Parameters:

  • key=[Read API Key] (this parameter is required if the robot is not public)
  • offset=[timezone offset in hours]
  • status=true (include status updates in feed)
  • location=true (include latitude, longitude, and elevation in feed)
  • callback=[function name] (used for JSONP cross-domain requests)

Optional Format:

  • txt

Retrieving a Field Feed

  Method: POST or GET
  Feed URL:
  http://bots.myrobots.com/channels/(channel_id)/field/(field_id).(format)

Optional Parameters:

  • key=[Read API Key]
  • results=[number of entries to retrieve (8000 max)]
  • days=[days to include in feed]
  • start=[start date] - YYYY-MM-DD%20HH:NN:SS
  • end=[end date] - YYYY-MM-DD%20HH:NN:SS
  • offset=[timezone offset in hours]
  • status=true (include status updates in feed)
  • location=true (include latitude, longitude, and elevation in feed)
  • min=[minimum value to include in response]
  • max=[maximum value to include in response]
  • round=x (round to x decimal places)
  • timescale=x (get first value in x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
  • sum=x (get sum of x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
  • average=x (get average of x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
  • median=x (get median of x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
  • callback=[function name] (used for JSONP cross-domain requests)

Retrieving the Last Entry in a Field Feed

   Method: POST or GET
   Feed URL:
   http://bots.myrobots.com/channels/(channel_id)/field/(field_id)/last.(format)

Optional Parameters:

   key=[Read API Key]
   offset=[timezone offset in hours]
   status=true (include status updates in feed)
   location=true (include latitude, longitude, and elevation in feed)
   callback=[function name] (used for JSONP cross-domain requests)

Optional Format:

  • txt

Optional Parameters for TXT format:

  • prepend=[text to add before the API response]
  • append=[text to add after the API response]

Retrieving Status Updates

   Method: POST or GET
   Feed URL:
   http://bots.myrobots.com/channels/(channel_id)/status.(format)

Optional Parameters:

  • key=[Read API Key]
  • offset=[timezone offset in hours]
  • callback=[function name] (used for JSONP cross-domain requests)

Chart API

The Chart API allows you to create an instant visualization of your data. The chart displays properly in all modern browsers and mobile devices. The chart can also show dynamic data by loading new data automatically.

  Chart URL:
  http://bots.myrobots.com/channels/(channel_id)/charts/(field_id)

Optional Chart Parameters:

  • title=[chart title, default: channel name]
  • xaxis=[chart’s x-axis label, default: Date]
  • yaxis=[chart’s y-axis label, default: field name]
  • color=[line color, default: red]
  • bgcolor=[background color, default: white]
  • type=[line, bar, or column, default: line]
  • width=x (chart width in pixels, iframe width will be 20px larger, default chart width: 400)
  • height=x (chart height in pixels, iframe height will be 20px larger, default chart height: 200)
  • dynamic=[true or false, default: false] (make chart update automatically every 15 seconds)
  • step=[true or false, default: false] (draw chart as a step chart)
  • export=[true or false, default: false] (show export buttons, so that chart can be saved as image)

Optional Feed Parameters:

  • key=[Read API Key]
  • results=[number of entries to retrieve (8000 max)]
  • days=[days to include in feed]
  • start=[start date] - YYYY-MM-DD%20HH:NN:SS
  • end=[end date] - YYYY-MM-DD%20HH:NN:SS
  • offset=[timezone offset in hours]
  • status=true (include status updates in feed)
  • location=true (include latitude, longitude, and elevation in feed)
  • min=[minimum value to include in response]
  • max=[maximum value to include in response]
  • round=x (round to x decimal places)
  • timescale=x (get first value in x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
  • sum=x (get sum of x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
  • average=x (get average of x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
  • median=x (get median of x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)

Embedding a Chart

To place a MyRobots.com Chart on your web page, use the Chart API as the source of an iframe.

Chart Embed Code:

  <iframe width="450" height="250" style="border: 1px solid #cccccc;"
  src="http://bots.myrobots.com/channels/(channel_id)/charts/(field_id)">
  </iframe>

Embedding a Dynamic Chart

To place a dynamic MyRobots Chart on your web page, use the Chart API as the source of an iframe and add the chart parameter ”dynamic=true”.

Alerts

Robots can react to certain conditions by using alerts. There are several types of conditions:

  • String - the robot's status or one of its sensors contains, starts with, is equal to, or eds with a certain string
  • Status - the same as string but only applying to the robot status.
  • Numeric - one of the robot's sensors is less than, equal to, or greater than a certain value.
  • Geo - the robot's coordinates are within or further than a certain distance of a geographical coordinate.
  • No data check - MyRobots.com raises a flag if the robot did not communicate for a certain period of time.

The alerts can trigger an email or a custom HTTP POST(V1.1 with standard headers).

The body of the email and HTTP post is defined in the Message field and the placeholder %%trigger%% can be used to include the sensor value that triggered the alert. This placeholder is only functional for alerts of type String, Status, and Numeric.

Personal tools
Namespaces
Variants
Actions