new _Connection()

Maps a connection to the HomeServer.
May not be directly instanced. An instance of the class is created by the method createConnection().

Example

Call of the 'createConnection()' method.

var conn = HomeServerConnector.createConnection("user1", "pw1", {"hostname": "192.168.123.234", "port": 443, "protocol": "wss"});

Properties

onConnect  HomeServerConnector._Connection~onConnectCallback

The callback method assigned here is called as soon as a connection has been established.

Example

Connection was established

function myConnectResponse() {
  ...
}
...
conn.onConnect = myConnectResponse;

onDisconnect  HomeServerConnector._Connection~onDisconnectCallback

The callback function assigned here is called as soon as there is no longer a connection.

Example

Connection terminated

function myDisconnectResponse(cause) {
  ...
}
...
conn.onDisconnect = myDisonnectResponse;

onError  HomeServerConnector._Connection~onErrorCallback

The callback function assigned here is called when an error occurs.

Example

Error occurs

function myErrorResponse(error) {
  ...
}
...
conn.onError = myErrorResponse;

onProjectInfo  HomeServerConnector._Connection~onProjectInfoCallback

The callback function assigned here is called when the information is available.

Example

conn.onProjectInfo = function(projectID) {};  

onStateChanged  HomeServerConnector._Connection~onStateChangedCallback

The callback function assigned here is called when the status of the current connection changes.

Example

Connection status has changed

function myStChgResponse(oldState, newState, error) {
  ...
}
...
conn.onStateChanged = myStChgResponse;

Methods

beginSubscription()

Initiation of a transaction to perform several subscriptions at the same time.
To optimise communication between the client and the HS, several subscriptions can be combined into one transaction. The client must then communicate with the HS only once instead of carrying out the procedure for each subscription separately.
The transaction is initiated with this method.
To end the transaction, endSubscription() is called.

Example

Subscription to 4 communication objects and one data archive in one transaction.

conn.beginSubscription():
var ko_1 = conn.getCommunicationObject("CO@1_1_1", function(err, value, isInit) {}); 
var ko_2 = conn.getCommunicationObject("CO@MyCoNo2", function(err, value, isInit) {});
var ko_3 = conn.getCommunicationObject("CO@TEST_CO_3", function(err, value, isInit) {});
var ko_4 = conn.getCommunicationObject("CO:31", function(err, value, isInit) {}); 
var arch = conn.getDataArchive("DA@MyDataArchive", function(err, data) {});
conn.endSubscription():

connect([_reconnect]) → Boolean

Establishment of connection is initiated.
An attempt to establish a connection is started immediately if a connection does not already exist.

Example

Attempts to connect to the HomeServer. Reconnection should be attempted if the connection is lost

var conn = HomeServerConnector.createConnection("user1", "pw1");
conn.connect(true);

Parameter

Name Type Optional Description

_reconnect

Boolean

Yes

true: If the connection is lost, a reconnection attempt is initiated after the Reconnect-Intervall .
false: If the connection is lost,no new connection attempt is initiated.

Defaults to true.

Returns

Boolean true: An attempt to establish a connection was initiated.
false: An attempt to set up a connection could not be initiated as a connection attempt was already initiated or a connection already exists.

destroy()

All events and references will be resolved. The WebSocket will be closed.
After this method has been called this instance can no longer be used.

Example

conn.destroy();

disconnect() → Boolean

Disconnection is initiated.

Example

conn.disconnect();
Returns

Boolean true: Disconnection was initiated.
false: There is no connection.

endSubscription()

Termination of a subscription transaction.
The mode of operation is explained in the section on the method for initiating the transaction: beginSubscription().

getCameraArchive(key[, subscriptionCallback]) → HomeServerConnector._CameraArchive

Returns an instance of a camera archive.

Example

var ca = conn.getCameraArchive("CA@MyCameraArchive", function(err, data) {});

Parameters

Name Type Optional Description

key

String

 

Key of camera archive

subscriptionCallback

function()

Yes

The Callback-Methode is called on subscription and on addition of a new entry.

Returns

HomeServerConnector._CameraArchive 

getCameraPicture(key) → HomeServerConnector._CameraPicture

Returns a camera image.

Example

var cp = conn.getCameraPicture("CP@MyCamera");

Parameter

Name Type Optional Description

key

String

 

Key of camera

Returns

HomeServerConnector._CameraPicture 

getCommunicationObject(key[, subscriptionCallback]) → HomeServerConnector._CommunicationObject

Returns an instance of a communication object (CO)

Example

var co = conn.getCommunicationObject("CO@1_1_1", function(err, value, isInit) {}); 

Parameters

Name Type Optional Description

key

String

 

Key of the communication object.

subscriptionCallback

function()

Yes

The Callback-Methode is called on subscription and on the change of value of the communication object.

Returns

HomeServerConnector._CommunicationObject 

getDataArchive(key[, subscriptionCallback]) → HomeServerConnector._DataArchive

Returns an instance of a data archive.

Example

var da = conn.getDataArchive("DA@MyDataArchive", function(err, data) {});

Parameters

Name Type Optional Description

key

String

 

Key of the data archive.

subscriptionCallback

function()

Yes

The Callback-Methode is called on subscription and on addition of a new entry.

Returns

HomeServerConnector._DataArchive 

getMessageArchive(key[, subscriptionCallback]) → HomeServerConnector._MessageArchive

Returns an instance of a message archive.

Example

var ma = conn.getMessageArchive("MA@MyMessageArchive", function(err, data) {});

Parameters

Name Type Optional Description

key

String

 

Key of the message archive.

subscriptionCallback

function()

Yes

The Callback-Methode is called on subscription and on addition of a new entry.

Returns

HomeServerConnector._MessageArchive 

getProjectId() → (String or Undefined)

Project ID. Is only available as soon as there is a connection to the HomeServer.

Example

Query project ID

var conn = HomeServerConnector.createConnection("user1", "pw1");
...
var pid = conn.getProjectId()
Returns

(String or Undefined) Project ID of the HomeServer project.

getReconnect() → Boolean

Provides the information whether a reconnection attempt should be made if the connection is lost.
This information can be set in the connect() method.

Example

Query reconnect status

var conn = HomeServerConnector.createConnection("user1", "pw1");
...
rc = conn.getReconnect()
Returns

Boolean true: If the connection is aborted, new attempts to connect should be made.

getReconnectInterval() → Number

Query reconnect attempt interval. Specification in seconds.

Example

Returns the interval in which attempts to reconnect are made if the connection was interrupted.

var conn = HomeServerConnector.createConnection("user1", "pw1");
...
ri = conn.getReconnectInterval();
Returns

Number Interval (in seconds) in which new attempts to connect are made.

getScene(key[, subscriptionCallback]) → HomeServerConnector._Scene

Returns an instance of a scene.

Example

var sc = conn.getScene("SC@MyScene", function(err, data) {});

Parameters

Name Type Optional Description

key

String

 

Key of the scene

subscriptionCallback

function()

Yes

The Callback-Methode is called on subscription and on learning a scene.

Returns

HomeServerConnector._Scene 

getSequence(key[, subscriptionCallback]) → HomeServerConnector._Sequence

Returns an instance of a sequence.

Example

var sq = conn.getSequence("SQ@MySequence", function(err, data) {});

Parameters

Name Type Optional Description

key

String

 

Key of the sequence

subscriptionCallback

function()

Yes

The Callback-Methode is called on subscription, on starting, stopping of the sequence or while the sequence is running.

Returns

HomeServerConnector._Sequence 

getState() → Number

Status of the connection as code.
See CONNECTION_STATE.

Example

Query status

var conn = HomeServerConnector.createConnection("user1", "pw1");
...
var st = conn.getState()
Returns

Number Status-Code.

getUniversalTimer(key[, subscriptionCallback]) → HomeServerConnector._UniversalTimer

Returns an instance of a universal timer (UT).

Example

var ca = conn.getUniversalTimer("TI@MyTimer", function(err, data) {});

Parameters

Name Type Optional Description

key

String

 

Key of the timer

subscriptionCallback

function()

Yes

The Callback-Methode is called on subscription and on changes to the timer.

Returns

HomeServerConnector._UniversalTimer 

getVacationCalendar(key[, subscriptionCallback]) → HomeServerConnector._VacationCalendar

Returns an instance of a holiday calendar.

Example

var vc = conn.getVacationCalendar("VC@MyCalendar", function(err, data) {});

Parameters

Name Type Optional Description

key

String

 

Key of holiday calendar

subscriptionCallback

function()

Yes

The Callback-Methode is called on subscription and on changes to the holiday calendar.

Returns

HomeServerConnector._VacationCalendar 

reset()

Resets all the HS objects and cancels the corresponding subscriptions.
All the HS objects generated via this connection can no longer be used after the call.

select(options[, Callback])

Returns a list of object keys with designations, as an option also the metadata of the objects.
The object options is transferred.

Example

Returns a maximum of 1000 communication objects with the tag "BM" (basement) or "Light" and no metadata

var conn = HomeServerConnector.createConnection("user1", "pw1");
...
function mySelectResponse(error, result, context) {
  ...
}
...
conn.select({"objectKey": "CO@*", "tags": ["BM", "Light"], "meta": False, "context": "test002"}, mySelectResponse)

Parameters

Name Type Optional Description

options

Object

 

Options (see 'Properties')

Callback

function()

Yes

The Callback-Methode which returns the return values.

Properties

Name Type Optional Description

options.objectKey

String

 

[Filter] Object type: (see object_types).

options.tags

String

Yes

[Filter] List of tags. A specified tag must match the tag defined in Expert.

options.search

String

Yes

[Filter] List of search words. All the objects where any word begins with the specified search word in their designation or description are found.

options.from

Number

Yes

Position as consecutive number, beginning with '0'.

Defaults to 0.

options.count

Number

Yes

Maximum number of returned object keys. (Maximum value: 1000)

Defaults to 1000.

options.meta

Boolean

Yes

true: Metadata of the selected objects are also returned.

Defaults to false.

options.context

Object

Yes

The Callback-Methode returns this object unedited.

setReconnectInterval([interval])

Set reconnect attempt interval. Specification in seconds.

Example

Sets the reconnect attempt interval to 30 seconds

var conn = HomeServerConnector.createConnection("user1", "pw1");
...
conn.setReconnectInterval(30);

Parameter

Name Type Optional Description

interval

Number

Yes

Defines the interval.

Defaults to 60.

Abstract types

inner

getCameraArchiveCallback(err, data)

Parameters

Name Type Optional Description

err

(Object or undefined)

 

Error object

data

Object

 

Meta information

Structure (on subscription)

undefined

Structure (on addition of an entry)

{
  "first":  Number,
  "last":   Number,
  "count":  Number,
  "pic_id": Number
}

Explanation

  • first - Unix time stamp (in seconds, milliseconds as a decimal value) of the oldest entry in the archive.
  • last - Unix time stamp (in seconds, milliseconds as a decimal value) of the youngest entry in the archive.
  • count - Number of entries in the archive.
  • pic_id - ID of the image. Is required for retrieval using getPicture().
inner

getCommunicationObjectCallback(err, data, isInit)

Parameters

Name Type Optional Description

err

(Object or undefined)

 

Error object

data

Object

 

Meta information

Structure (on subscription and on change to value)

{
  "value": Number|String
}

Explanation

  • value - Value of the communication object

isInit

Boolean

 

true: On subscription - false: In case of value change

inner

getDataArchiveCallback(err, data)

Parameters

Name Type Optional Description

err

(Object or undefined)

 

Error object

data

Object

 

Meta information

Structure (on subscription)

null

Structure (on addition of an entry)

{
  "first": Number,
  "last":  Number,
  "count": Number
}

Explanation

  • first - Unix time stamp (in seconds, milliseconds as a decimal value) of the oldest entry in the archive.
  • last - Unix time stamp (in seconds, milliseconds as a decimal value) of the youngest entry in the archive.
  • count - Number of entries in the archive.
inner

getMessageArchiveCallback(err, data)

Parameters

Name Type Optional Description

err

(Object or undefined)

 

Error object

data

Object

 

Meta information

Structure (on subscription)

null

Structure (on addition of an entry)

{
  "first": Number,
  "last":  Number,
  "count": Number,
  "token": String,
  "text":  String
}

Explanation

  • first - Unix time stamp (in seconds, milliseconds as a decimal value) of the oldest entry in the archive.
  • last - Unix time stamp (in seconds, milliseconds as a decimal value) of the youngest entry in the archive.
  • count - Number of entries in the archive.
  • token - Abbreviation defined in Expert for the entry.
  • text - Text defined in Expert for the entry.
inner

getSceneCallback(err, data)

Parameters

Name Type Optional Description

err

(Object or undefined)

 

Error object

data

Object

 

Meta information

Structure (on subscription)

null

Structure (on new teaching in)

{
  "ts":       Number,
  "modified": Boolean

ÿ ኘ

Explanation

  • ts - Unix time stamp (in seconds, milliseconds as a decimal value).
  • modified - true: The scene was taught in again.
inner

getSequenceCallback(err, data)

Parameters

Name Type Optional Description

err

(Object or undefined)

 

Error object

data

Object

 

Meta information

Structure (on subscription)

null

Structure (on start, stop or expiry)

{
  "ts":      Number,
  "running": Boolean
}

Explanation

  • ts - Unix time stamp (in seconds, milliseconds as a decimal value).
  • running - true: The sequence is running.
inner

getUniversalTimerCallback(err, data)

Parameters

Name Type Optional Description

err

(Object or undefined)

 

Error object

data

Object

 

Meta information

Structure (on subscription)

undefined

Structure (in the event of change to the timer)

{
  ts:       Number,
  active:   Boolean,
  modified: Boolean
}

Explanation

  • ts - Unix time stamp (in seconds, milliseconds as a decimal value) of the change.
  • active - true: the timer is active.
  • modified - true: the timer was changed (event created, changed or deleted).
inner

getVacationCalendarCallback(err, data)

Parameters

Name Type Optional Description

err

(Object or undefined)

 

Error object

data

Object

 

Meta information

Structure (on subscription) and in the event of change to the holiday calendar

 {
  "active": Boolean,
  "from":   Date,
  "to":     Date
}

Explanation

  • active - true: the holiday calendar is active.
  • from - Date object. Start of the period.
  • to - Date object. End of the period.
inner

onConnectCallback()

Example

Connection was established

function myConnectResponse() {
  ...
}
...
conn.onConnect = myConnectResponse;
inner

onDisconnectCallback(cause)

Example

Connection terminated

function myDisconnectResponse(cause) {
  ...
}
...
conn.onDisconnect = myDisonnectResponse;

Parameter

Name Type Optional Description

cause

Number

 

WebSocket status code. Reason for disconnection.

inner

onErrorCallback(err)

Example

Error occurs

function myErrorResponse(err) {
  ...
}
...
conn.onError = myErrorResponse;

Parameter

Name Type Optional Description

err

(Object or undefined)

 

Error object

inner

onProjectInfoCallback(projectID)

Parameter

Name Type Optional Description

projectID

String

 

ID of project, e.g. "20160331114440548".

inner

onStateChangedCallback(oldState, newState[, error])

Example

Connection status has changed

function myStChgResponse(oldState, newState, error) {
  ...
}
...
conn.onStateChanged = myStChgResponse;

Parameters

Name Type Optional Description

oldState

Number

 

Status value before the change.

newState

Number

 

Status value after the change.

error

Object

Yes

Error object.

inner

selectCallback(err, result, context)

Callback method of HomeServerConnector._Connection.select().

Example

Returns a maximum of 1000 communication objects with the tag "BM" (basement) or "Light" and no metadata

var conn = HomeServerConnector.createConnection("user1", "pw1");
...
function mySelectResponse(error, result, context) {
  ...
}
...
conn.select({"objectKey": "CO@*", "tags": ["BM", "Light"], "meta": False, "context": "test002"}, mySelectResponse)

Parameters

Name Type Optional Description

err

(Object or undefined)

 

Error object.
The following errors may occur: "no connection", "connection lost", "server error", "too many selects".

result

Object

 

List of object keys and designations, optionally with metadata.

context

Object

 

The unmodified context specified on the call.