gigaset-elements-api v0.5.2

gigaset-elements-api

Library to access Gigaset Elements API.

Installation

npm install gigaset-elements-api

// or

yarn add gigaset-elements-api

Usage

Getting started

import { GigasetElementsApi } from "gigaset-elements-api";

const api = new GigasetElementsApi({
  email: "username/email for accessing GE cloud",
  password: "password of accessing GE cloud",
});

The constructor of the GigasetElementsApi class acccepts the following configuration object:

{
  // required
  email: "<email>", // username/email for accessing GE cloud
  password: "<password>", // password of accessing GE cloud
  // optional
  authorizeHours: 6, // defaults to 6, number of hours after which GE cloud needs reauthorization
  requestLogger: (message: string) => void, // for logging all http requests
}

Methods

isMaintenance

Check whether GE cloud is in maintenance mode and currently not available

api.isMaintenance(): Promise<boolean>

getSystemHealth

Retrive system health data.

api.getSystemHealth(): Promise<IGigasetElementsSystemHealth>

getBaseStations

Retrieves base station and sensor data. Automatically handles authorization if required.

api.getBaseStations(): Promise<IBaseStationRoot>;

getElements

Retrieves elements, including sensor data (i.e. temperature for universal sensor). Automatically handles authorization if required.

api.getElements(): Promise<IElementRoot>;

getRecentEvents

Retrieves the most recent events that occured until a given point in time. Events are sorted by timestamp in descending order. Only the most recent limit number of events will be returned.

api.getRecentEvents(until: Date | number, limit = 500): Promise<IEventRoot>;

getEvents

Retrieves events that occured during a time period. Events are sorted by timestamp in descending order. Limit is applied from the end of the period.

api.getEvents(from: Date | number, to: Date | number, limit = 500): Promise<IEventRoot>

getAllEvents

Utility method to retrieves all events that occured during a time period, using multiple requests if more than batchSize events occured in this period. Events are sorted by timestamp in descending order. If to is not specified, the current date will be used.

api.getAllEvents(from: Date | number, to?: Date | number, batchSize = 500): Promise<IEventsItem[]>

sendCommand

Sends a command for an endNode, i.e. "on" or "off" for plugs. Throws if the command is invalid (HTTP 400), i.e. when sending "off" to a plug that is already turned off.

api.sendCommand(baseStationId: string, endNodeId: string, commandName: string): Promise<void>;

setThermostat

Sets the setPoint for a thermostat. !completely untested due to lack of hardware!

api.setThermostat(baseStationId: string, endNodeId: string, setPoint: number): Promise<void>;

setUserAlarm

Turn user alarm (panic button) on or off,

api.setUserAlarm(on: boolean): Promise<void>;

setAlarmMode

Updates the active alarm mode.

setAlarmMode(baseStationId: string, mode: "away" | "home" | "night" | "custom"): Promise<void>

authorize

Authorize against the GE cloud. Retrieves and stores authorization cookie for further api requests. Usually this is done automatically by methods that need authorization like getRecentEvents and doesn't neet to be called manually.

api.authorize(): Promise<true>;

needsAuth

Check whether authorization is due, i.e. last authorization was more than authorizeHours ago. Usually this is only used internally.

api.needsAuth(): boolean;

Limitations

• The library was designed to fit my needs for an ioBroker adapter. If additional functionality is required please open an issue.

• Event data in the Gigaset Elements cloud reaches back 1 month, and a maximum of 500 events can be retrieved per api call as per my tests.

So far the library has been tested with the following sensors, which have also test data available:

In addition definitions and test data for IP Phones (gp02) has been included.

Contributing

Running tests

npm test

// or with watch mode
npm run test:watch

Adding test data for additional element or event types

npm run generate:merge-test-data

See also Test Data

Acknowledgements

This library would not be possible without the awsome work of https://github.com/ycardon/gigaset-elements-proxy and https://github.com/dynasticorpheus/gigasetelements-ha.

Hardware sponsors:

• Voggl93 (Plug v1)