Skip to content

README.md

Latest commit

 

History

History
432 lines (385 loc) · 25.1 KB

README.md

File metadata and controls

432 lines (385 loc) · 25.1 KB
Raw

API 1.0 and 1.1 are stopped. Please refer to this link for API 1.3

Warning (Sorry for the inconvenience)

  • Please use timestamp after 1386168197000 for retrieving data. Because for performance reason, the old sensor reading data is archived. The new data started from 6:43am, Dec 4, 2013
  • Please refer to this link for the new device_id. The old device_id in this API doc may not be available any more.

Released under a Dual Licensing / GPL 3. Sensor Service Platform APIs Version 1.0

Advisors: Jia Zhang, Bob Iannucci, Martin Griss, Steven Rosenberg, Anthony Rowe
Current contributors: Bo Liu, Lyman Cao, Chris Lee
Past Contributors: Yuan Ren, Mark Hennessy, Kaushik Gopal, Sean Xiao, Sumeet Kumar, David Pfeffer, Basmah Aljedia

EXECUTIVE SUMMARY

On top of CMU SensorAndrew, the largest nation-wide campus sensor network, our Sensor Data and Service Platform (SDSP) aims to build a software service layer serving sensor data service discovery, reuse, composition, mashup, provisioning, and analysis. Another major objective of our project is to support SDSP-empowered innovative application design and development. Supported by a cloud computing enrironment with high-performance database, SDSP provides a platform to enable and facilitate a variety of research projects at CMUSV in the areas of mobile services, internet of things, cloud computing, big data analytics, software as a service, and social services.

Service URL:

http://einstein.sv.cmu.edu

Overview:

Currently we are providing APIs in 3 categores:

Category 1: Post sensor readings

Category 2: Query database for sensor readings

Category 3: Query database for metadata

Category 4: Manage metadata---under construction

Detailed Usages:

Note: all TimeStamps are in Unix epoch time format to millisecond. Conversion from readable timestamp format to Unix epoch timestamp can be found in http://www.epochconverter.com

  1. GET ALL DEVICES

    • Purpose: Query all registered devices' metadata.
    • Method: GET
    • URL: http://einstein.sv.cmu.edu/get_devices/<"result_format">
    • Semantics:
      • uri: User-defined identifier for a device. Each uri is an identifier unique to the corresponding device
      • device_type: Model of the device. A device is a container (i.e., physical device) object that comprises one or more sensors and is capable of transmitting their readings over a network to a Device Agent.
      • device_agent: A local server or proxy that manages a set of devices registered to it. Device agents can receive data from devices, convert data to another format (eg. JSON), and can transmit it to central server over a LAN or WAN.
      • device_location: The location of the device that is transmitting sensor data.
      • result_format: Either json or csv (2 formats are supported).
    • Sample Usages:

  2. GET SENSOR TYPES OF A DEVICE

  3. PUBLISH SENSOR READINGS

    • Purpose: Publish sensor readings to sensor data service platform.
    • Method: POST
    • URL: http://einstein.sv.cmu.edu/sensors
    • Semantics: As a POST method, the API cannot be directly executed through a web browser. Instead, it may be executed through Rails, JQuery, Python, BASH, etc.
      • device_id (string): Unique device uri/id.
      • timestamp (int): Recording timestamp of the sensor reading in Unix epoch timestamp format.
      • sensor_type (string): Type of the sensor, e.g., temperature, CO2 Levels, etc. It is user's responsibility to tag the correct sensor type to the sensor reading.
      • sensor_value (double): The value of the sensor reading. It is user's responsibility to calibrate the sensor readings before publishing.
    • Sensor data format: {"id": <"device_id">, "timestamp": <"timestamp">, <"sensor_type">: <"sensor_value">}
      Note: more than one (sensor_type:sensor_value) pairs can be included in a json file.
    • Sample Usages:
      • Command Line Example:
        1. Prepare input sensor reading data in a json file (please modify the timestamp to a different value):
          • "sample_reading.json" file contains: {"id":"test", "timestamp": 1373566899000, "temp": 123}
        2. curl -H "Content-Type: application/json" -d @sample_reading.json "http://einstein.sv.cmu.edu/sensors"
      • Result: "saved" if the sensor readings have been successfully added to the database.

  4. GET SENSOR READINGS OF A TYPE OF SENSOR IN A DEVICE AT A TIME

    • Purpose: Query sensor readings for a specific type of sensor, in a particular device, at a specific time point.
    • Method: GET
    • URL: http://einstein.sv.cmu.edu/sensors/<"device_id">/<"timestamp">/<"sensor_type">/<"result_format">
    • Semantics:
      • device_id: Unique uri/identifier of a device.
      • timestamp: Time of the readings to query.
      • sensor_type: Type of the sensor (e.g., temperature, CO2, etc.) to query.
      • result_format: Either json or csv.
    • Sample Usages:

  5. GET SENSOR READINGS IN A TIME RANGE FOR A DEVICE

    • Purpose: Query sensor readings for a specific type of sensor, in a particular device, for a specific time range.
    • Method: GET
    • URL: http://einstein.sv.cmu.edu/sensors/<"device_id">/<"start_time">/<"end_time">/<"sensor_type">/<"result_format">
    • Semantics:
      • device_id: Unique uri/identifier of a device.
      • start_time: Start time to retrieve the sensor readings.
      • end_time: End time to retreive the sensor readings.
      • sensor_type: Type of the sensor (e.g., temperature, CO2, etc.) to retrieve its readings.
      • result_format: Either json or csv.
    • Sample Usages:

  6. GET CURRENT SENSOR READINGS AT A TIME POINT FOR A TYPE OF SENSOR IN ALL REGISTERED DEVICES

  7. GET LATEST SENSOR READINGS AT A TIME POINT FOR A TYPE OF SENSOR IN ALL REGISTERED DEVICES

    • Purpose: Query all latest sensor readings, of a specific sensor type contained in all devices. If no reading for a sensor in the last 60 seconds, the latest stored reading of the corresponding sensor will be returned.
    • Method: GET
    • URL: http://einstein.sv.cmu.edu/lastest_readings_from_all_devices/<"sensor_type">/<"result_format">
    • Semantics:
      • sensor_type: Type of the sensor (e.g., temperature, CO2, etc.).
      • result_format: Either json or csv.
      • Note: The difference between API#7 and API#6 (last_readings_from_all_devices) given the current timestamp is that, API#7 returns the last readings stored for each device even if it is more than 60 seconds old.
    • Sample Usages:

  8. ADD SENSOR TYPE

    • Purpose: Add a new sensor type to sensor data service platform.
    • Method: POST
    • URL: http://einstein.sv.cmu.edu/add_sensor_type
    • Semantics: As a POST method, the API cannot be directly executed through a web browser. Instead, it may be executed through Rails, JQuery, Python, BASH, etc.
      • sensor_type (string): Name of the sensor type.
      • user_defined_fields (string): User defined fields.
    • Sensor type metadata format: {"sensor_type": <"sensor_type">, "user_defined_fields": <"user_defined_fields">}
    • Sample Usages:
      • Command Line Example:
        1. Prepare input sensor type metadata in a json file:
          • "sensor_type.json" file contains: {"sensor_type": "Humidity", "user_defined_fields": "For test"}
        2. curl -H "Content-Type: application/json" -d @sensor_type.json "http://einstein.sv.cmu.edu/add_sensor_type"
      • Result: "sensor type saved" if the sensor type metadata has been successfully added to the database.

  9. ADD SENSOR

    • Purpose: Add a new sensor to sensor data service platform.
    • Method: POST
    • URL: http://einstein.sv.cmu.edu/add_sensor
    • Semantics: As a POST method, the API cannot be directly executed through a web browser. Instead, it may be executed through Rails, JQuery, Python, BASH, etc.
      • print_name (string): Name of the sensor.
      • sensor_type (string): Its sensor type.
      • device_id (string): The device ID it belongs to.
      • user_defined_fields (string): User defined fields.
    • Sensor metadata format: {"print_name": <"print_name">, "sensor_type": <"sensor_type">, "device_id": <"device_id">, "user_defined_fields": <"user_defined_fields">}
    • Sample Usages:
      • Command Line Example:
        1. Prepare input sensor metadata in a json file:
          • "sensor.json" file contains: {"print_name": "test_sensor", "sensor_type": "Humidity", "device_id": "test_id", "user_defined_fields": "For test"}
        2. curl -H "Content-Type: application/json" -d @sensor.json "http://einstein.sv.cmu.edu/add_sensor"
      • Result: "sensor saved" if the sensor metadata have been successfully added to the database.

  10. ADD DEVICE TYPE

    • Purpose: Add a new device type to sensor data service platform.
    • Method: POST
    • URL: http://einstein.sv.cmu.edu/add_device_type
    • Semantics: As a POST method, the API cannot be directly executed through a web browser. Instead, it may be executed through Rails, JQuery, Python, BASH, etc.
      • device_type_name (string): Name of the device type.
      • manufacturer (string): Name of the manufacturer.
      • version (string): Version of the device type.
      • user_defined_fields (string): User defined fields.
    • Sensor type metadata format: {"device_type_name": <"device_type_name">, "manufacturer": <"manufacturer">, "version": <"version">, "user_defined_fields": <"user_defined_fields">}
    • Sample Usages:
      • Command Line Example:
        1. Prepare input device type metadata in a json file:
          • "device_type.json" file contains: {"device_type_name": "test_device_type", "manufacturer": "TI", "version": "1.0", "user_defined_fields": "For test"}
        2. curl -H "Content-Type: application/json" -d @sensor_type.json "http://einstein.sv.cmu.edu/add_device_type"
      • Result: "device type saved" if the device type metadata has been successfully added to the database.

  11. ADD DEVICE

    • Purpose: Add a new device to sensor data service platform.
    • Method: POST
    • URL: http://einstein.sv.cmu.edu/add_device
    • Semantics: As a POST method, the API cannot be directly executed through a web browser. Instead, it may be executed through Rails, JQuery, Python, BASH, etc.
      • device_type (string): Name of the device type.
      • device_agent (string): Name of the device agent.
      • network_address (string): The device id (i.e., network address, uri, macaddress to date). This device_id will be needed as a reference in all consequent senarios.
      • location_description (string): Location.
      • latitude (string): Latitude.
      • longitude (string): Longitude.
      • altitude (string): Altitude.
      • position_format_system (string): Format of the position.
      • user_defined_fields (string): User defined fields.
    • Sensor metadata format: {"device_type": <"device_type">, "device_agent": <"device_agent">, "network_address": <"network_address">, "location_description": <"location_description">, "latitude": <"latitude">, "longitude": <"longitude">, "altitude": <"altitude">, "position_format_system": <"position_format_system">, "user_defined_fields": <"user_defined_fields">}
    • Sample Usages:
      • Command Line Example:
        1. Prepare input device metadata in a json file:
          • "device.json" file contains: {"device_type": "test_device_type", "device_agent": "test_device_agent", "network_address": "test_network_address", "location_description": "test_location_description", "latitude": "test_latitude", "longitude": "test_longitude", "altitude": "test_altitude", "position_format_system": "test_position_format_system", "user_defined_fields": "For test"}
        2. curl -H "Content-Type: application/json" -d @device.json "http://einstein.sv.cmu.edu/add_device"
      • Result: "device saved" if the device metadata have been successfully added to the database.

  12. GET SENSOR READINGS OF A TYPE OF SENSOR IN A DEVICE AT A TIME BY READABLE TIME

  13. GET SENSOR READINGS IN A TIME RANGE FOR A DEVICE

Examples:

  1. Consume Rest API in Python

    • GET
       
      import json, requests
      response = requests.get("http://einstein.sv.cmu.edu/get_devices/json")
      print(response.json())
    • POST
       
      import requests
      requests.post("http://einstein.sv.cmu.edu/sensors", data={}, headers={}, files={}, cookies=None, auth=None)

  2. Consume Rest API in Java

    • GET
       
   import java.net.HttpURLConnection;
   import java.net.URL;
   public static String httpGet(String urlStr) throws IOException {
   		URL url = new URL(urlStr);
   		HttpURLConnection conn = (HttpURLConnection) url.openConnection();
   
   		if (conn.getResponseCode() != 200) {
   			throw new IOException(conn.getResponseMessage());
   		}
   
   		// Buffer the result into a string
   		BufferedReader rd = new BufferedReader(new InputStreamReader(conn.getInputStream()));
   		StringBuilder sb = new StringBuilder();
   		String line;
   		while ((line = rd.readLine()) != null) {
   			sb.append(line);
   		}
   		rd.close();
   
   		conn.disconnect();
   		return sb.toString();
	}
   

       
   import java.io.BufferedReader;
   import java.io.IOException;
   import java.io.InputStreamReader;
   import java.io.OutputStream;
   import java.io.OutputStreamWriter;
   import java.io.Writer;
   import java.net.HttpURLConnection;
   import java.net.URL;
   import com.google.gson.JsonObject;
   
   public class SensorReadingPostExample {
      	public static void main(String args[]) throws Exception {
      		String URLStr = "http://einstein.sv.cmu.edu/sensors";
      		java.util.Date date = new java.util.Date();
      		
      		JsonObject jo = new JsonObject();
      		//Sample data
      		jo.addProperty("timestamp", date.getTime()); //Long type
      		jo.addProperty("id", "my_test_device_id");   //String type
      		jo.addProperty("temp", 888);                 //Double type
      		   
      		httpPostSensorReading(URLStr, jo.toString());
      	}
      
      	public static String httpPostSensorReading(String urlStr, String jsonString) throws Exception {
      		URL url = new URL(urlStr);
      		HttpURLConnection conn = (HttpURLConnection) url.openConnection();
      		conn.setRequestMethod("POST");
      		conn.setRequestProperty("Content-Type", "application/json");
      		conn.setRequestProperty("Accept", "application/json");
      		conn.setDoOutput(true);
      
      		// Create the form content
      		OutputStream out = conn.getOutputStream();
      		Writer writer = new OutputStreamWriter(out, "UTF-8");
      
      		writer.write(jsonString);
      
      		writer.close();
      		out.close();
      
      		if (conn.getResponseCode() != 200) {
      			throw new IOException(conn.getResponseMessage());
      		}
      
      		// Buffer the result into a string
      		BufferedReader rd = new BufferedReader(new InputStreamReader(
      				conn.getInputStream()));
      		StringBuilder sb = new StringBuilder();
      		String line;
      		while ((line = rd.readLine()) != null) {
      			sb.append(line);
      		}
      		rd.close();
      
      		conn.disconnect();
      		return sb.toString();
      	}
   
   }

To do items:

  • Provide APIs that allow users to specify human time specification (time zone?).
    • key name of "timestamp"? in json
    • which apis need readable time
  • How about when some fields are added or changed for some sensors?
  • Rethink the design of HANA tables, to leverage HANA indexing previlege while keeping records info.
  • Mobile sensor into the picture (location: room, GPS, configurable)?