The API > JSON API > REST Resources > Devices > GET

Overview

Get the actual state of one device and continue directly with updates of the device via a telegram stream.

Transmitted telegrams of a single device

Client to Gateway:

Resource Path	HTTP method
/devices/{deviceId}/stream?direction={direction}&delimited={delimited}&output={output}	GET

necessary additional call parameters:

parameter	valid values	call option	functionality
deviceId	deviceID \| friendlyId	required	SenderID of Enocean device, EnOcean modules usually send telegrams with their unique 32-bit Chip ID. In the other case, these are the Base ID of the EnOcean device.
direction (optional)	from \| to \| both	default: both	direction of transport (from device sent / to device sent / both directions )
delimited (optional)	length \| lengthBytes \| lengthCharacters \| newLine \| emptyLine	default: emptyLine	Format and delimiter options
output (optional)	formatted \| singleLine	default: formatted	Format and delimiter options

response Gateway to Client:

parameter				datatype	value / formatting	description
header				object	{}
states				array of objects	[{}]
	deviceId			string	xxxxxxxx	SenderID of Enocean device, EnOcean modules usually send telegrams with their unique 32-bit Chip ID. In the other case, these are the Base ID of the EnOcean device.
	friendlyId			string		User-assigned name of EnOcean device. Must be unique.
	physicalDevice (optional)			string		User-assigned name to group actuators and sensors.
	functions			array of objects	[{}]
			key	string		Technical key of function.
			channel (optional)	integer		Channel if supported by this device.
			value	float		Value of the function.
			unit (optional)	string	[unit]	Unit ISO.
			meaning (optional)	string		Description of value in English.
			timestamp	string	yyyy-mm-ddT hh:mm:ss.sss+ hhmm	Timestamp function value was received in case of last state functions.
			age	integer		Age of function value in case of last state functions in milli seconds.
followed by live telegram stream
header				object	{}
telegram				object	{}
Case 1/2: telegram of known device
	deviceId			string	xxxxxxxx	SenderID of Enocean device, EnOcean modules usually send telegrams with their unique 32-bit Chip ID. In the other case, these are the Base ID of the EnOcean device.
	friendlyId			string		User-assigned name of EnOcean device. Must be unique.
	physicalDevice (optional)			string		User-assigned name to group actuators and sensors.
	timestamp			string	yyyy-mm-ddT hh:mm:ss.sss+ hhmm	telegram transmission time in UTC format
	direction			string	from \| to	direction of transport (from device sent / to device sent)
	functions			array of objects	[{}]
			key	string		Technical key of function.
			channel (optional)	integer		Channel if supported by this device.
			value	float		Value of the function.
			unit (optional)	string	[unit]	Unit ISO.
			meaning (optional)	string		Description of value in English.
	telegramInfo			object	{}
			data	string	x byte hex value	Payload of ERP telegrams or ESP packets
			status	integer		identifies if the subtelegram is transmitted from a repeater and the type of integrity control mechanism used (note: not present in a RPS telegram)
			dbm	integer		signal strength of received / transmitted telegram
			rorg	string	1 byte hex value	identifier for subtelegram type
Case 2/2: telegram of unknown device (only if Filtermode is Off)
	deviceId			string	4 byte hex value	SenderID of Enocean device, EnOcean modules usually send telegrams with their unique 32-bit Chip ID. In the other case, these are the Base ID of the EnOcean device.
	timestamp			string	yyyy-mm-ddT hh:mm:ss.sss+ hhmm	telegram transmission time in UTC format
	direction			string	from \| to	direction of transport (from GW sent or received)
	telegramInfo			object	{}
		data		string	x byte hex value	Payload of ERP telegrams or ESP packets.
		status		integer		identifies if the subtelegram is transmitted from a repeater and the type of integrity control mechanism used. (note: not present in a RPS telegram)
		dbm		integer		signal strength of received / transmitted telegram
		rorg		string	1 byte hex value	identifier for subtelegram type

Example:

In that example we received various telegrams from a weatherstation.

Basic structure of gateway response:

http://hostname:api_port/devices/weatherstation/stream

{
  "header" : {
    "httpStatus" : 200,
    "content" : "states",
    "timestamp" : "2016-05-04T15:24:05.453+0200"
  },
  "states" : [ {
    "deviceId" : "01842329",
    "friendlyId" : "WeatherStation",
    "functions" : [ {
      "key" : "dawnSensor",
      "value" : 999.00,
      "unit" : "lx",
      "timestamp" : "2016-05-04T15:18:38.909+0200",
      "age" : 326544
    }, {
      "key" : "dayNight",
      "value" : "day",
      "meaning" : "Day",
      "timestamp" : "2016-05-04T15:18:38.909+0200",
      "age" : 326544
    }, {
      "key" : "hemisphere",
      "value" : "north",
      "meaning" : "North",
      "timestamp" : "2016-05-04T15:18:38.709+0200",
      "age" : 326744
    }, {
      "key" : "rainIndication",
      "value" : "noRain",
      "meaning" : "No rain",
      "timestamp" : "2016-05-04T15:18:38.909+0200",
      "age" : 326544
    }, {
      "key" : "sunEast",
      "value" : 1764.71,
      "unit" : "lx",
      "timestamp" : "2016-05-04T15:18:38.709+0200",
      "age" : 326744
    }, {
      "key" : "sunSouth",
      "value" : 2941.18,
      "unit" : "lx",
      "timestamp" : "2016-05-04T15:18:38.709+0200",
      "age" : 326744
    }, {
      "key" : "sunWest",
      "value" : 588.24,
      "unit" : "lx",
      "timestamp" : "2016-05-04T15:18:38.709+0200",
      "age" : 326744
    }, {
      "key" : "temperature",
      "value" : 25.88,
      "unit" : "°C",
      "timestamp" : "2016-05-04T15:18:38.909+0200",
      "age" : 326545
    }, {
      "key" : "windSpeed",
      "value" : 0.00,
      "unit" : "m/s",
      "timestamp" : "2016-05-04T15:18:38.909+0200",
      "age" : 326545
    } ]
  } ]
}
{
  "header" : {
    "content" : "telegram",
    "timestamp" : "2016-05-04T15:24:44.653+0200"
  },
  "telegram" : {
    "deviceId" : "01842329",
    "friendlyId" : "WeatherStation",
    "timestamp" : "2016-05-04T15:24:44.653+0200",
    "direction" : "from",
    "functions" : [ {
      "key" : "sunWest",
      "value" : 0.00,
      "unit" : "lx"
    }, {
      "key" : "sunSouth",
      "value" : 588.24,
      "unit" : "lx"
    }, {
      "key" : "sunEast",
      "value" : 588.24,
      "unit" : "lx"
    }, {
      "key" : "hemisphere",
      "value" : "north",
      "meaning" : "North"
    } ],
    "telegramInfo" : {
      "data" : "00010128",
      "status" : "0",
      "dbm" : -82,
      "rorg" : "A5"
    }
  }
}
{
  "header" : {
    "content" : "telegram",
    "timestamp" : "2016-05-04T15:28:56.379+0200"
  },
  "telegram" : {
    "deviceId" : "01842329",
    "friendlyId" : "WeatherStation",
    "timestamp" : "2016-05-04T15:28:56.379+0200",
    "direction" : "from",
    "functions" : [ {
      "key" : "sunWest",
      "value" : 0.00,
      "unit" : "lx"
    }, {
      "key" : "sunSouth",
      "value" : 588.24,
      "unit" : "lx"
    }, {
      "key" : "sunEast",
      "value" : 588.24,
      "unit" : "lx"
    }, {
      "key" : "hemisphere",
      "value" : "north",
      "meaning" : "North"
    } ],
    "telegramInfo" : {
      "data" : "00010128",
      "status" : "0",
      "dbm" : -86,
      "rorg" : "A5"
    }
  }
}
{
  "header" : {
    "content" : "telegram",
    "timestamp" : "2016-05-04T15:28:56.580+0200"
  },
  "telegram" : {
    "deviceId" : "01842329",
    "friendlyId" : "WeatherStation",
    "timestamp" : "2016-05-04T15:28:56.580+0200",
    "direction" : "from",
    "functions" : [ {
      "key" : "dawnSensor",
      "value" : 999.00,
      "unit" : "lx"
    }, {
      "key" : "temperature",
      "value" : 25.88,
      "unit" : "°C"
    }, {
      "key" : "windSpeed",
      "value" : 0.00,
      "unit" : "m/s"
    }, {
      "key" : "dayNight",
      "value" : "day",
      "meaning" : "Day"
    }, {
      "key" : "rainIndication",
      "value" : "noRain",
      "meaning" : "No rain"
    } ],
    "telegramInfo" : {
      "data" : "FF8C0018",
      "status" : "0",
      "dbm" : -86,
      "rorg" : "A5"
    }
  }
}

GET /devices/{deviceId}/stream

GET /devices/{deviceId}/stream