klf-200-api
Version:
This module provides a wrapper to the socket API of a Velux KLF-200 interface. You will need at least firmware 0.2.0.0.71 on your KLF interface for this library to work.
232 lines (231 loc) • 10.5 kB
TypeScript
/// <reference types="node" />
/// <reference types="node" />
import { ConnectionOptions } from "tls";
import { KLF200SocketProtocol } from "./KLF200-API/KLF200SocketProtocol.js";
import { GatewayCommand, IGW_FRAME_RCV, IGW_FRAME_REQ } from "./KLF200-API/common.js";
import { Disposable, Listener } from "./utils/TypedEvent.js";
/**
* Interface for the connection.
*
* @export
* @interface IConnection
*/
export interface IConnection {
/**
* Logs in to the KLF interface by sending the GW_PASSWORD_ENTER_REQ.
*
* @param {string} password The password needed for login. The factory default password is velux123.
* @param {number} [timeout] A timeout in seconds. After the timeout the returned promise will be rejected.
* @returns {Promise<void>} Returns a promise that resolves to true on success or rejects with the errors.
* @memberof IConnection
*/
loginAsync(password: string, timeout?: number): Promise<void>;
/**
* Logs out from the KLF interface and closes the socket.
*
* @param {number} [timeout] A timeout in seconds. After the timeout the returned promise will be rejected.
* @returns {Promise<void>} Returns a promise that resolves to true on successful logout or rejects with the errors.
* @memberof IConnection
*/
logoutAsync(timeout?: number): Promise<void>;
/**
* Sends a request frame to the KLF interface.
*
* @param {IGW_FRAME_REQ} frame The frame that should be sent to the KLF interface.
* @param {number} [timeout] A timeout in seconds. After the timeout the returned promise will be rejected.
* @returns {Promise<IGW_FRAME_RCV>} Returns a promise with the corresponding confirmation message as value.
* In case of an error frame the promise will be rejected with the error number.
* If the request frame is a command (with a SessionID) than the promise will be
* resolved by the corresponding confirmation frame with a matching session ID.
* @memberof IConnection
*/
sendFrameAsync(frame: IGW_FRAME_REQ, timeout?: number): Promise<IGW_FRAME_RCV>;
/**
* Add a handler to listen for confirmations and notification.
* You can provide an optional filter to listen only to
* specific events.
*
* @param {Listener<IGW_FRAME_RCV>} handler Callback functions that is called for an event
* @param {GatewayCommand[]} [filter] Array of GatewayCommand entries you want to listen to. Optional.
* @returns {Disposable} Returns a Disposable that you can call to remove the handler.
* @memberof Connection
*/
on(handler: Listener<IGW_FRAME_RCV>, filter?: GatewayCommand[]): Disposable;
/**
* Add a handler to listen for confirmations and notification.
* You can provide an optional filter to listen only to
* specific events.
*
* @param {Listener<IGW_FRAME_REQ>} handler Callback functions that is called for an event
* @param {GatewayCommand[]} [filter] Array of GatewayCommand entries you want to listen to. Optional.
* @returns {Disposable} Returns a Disposable that you can call to remove the handler.
* @memberof Connection
*/
onFrameSent(handler: Listener<IGW_FRAME_REQ>, filter?: GatewayCommand[]): Disposable;
/**
* Gets the underlying socket protocol handler.
*
* @type {KLF200SocketProtocol}
* @memberof IConnection
*/
readonly KLF200SocketProtocol?: KLF200SocketProtocol;
}
/**
* The Connection class is used to handle the communication with the Velux KLF interface.
* It provides login and logout functionality and provides methods to run other commands
* on the socket API.
*
* ```
* const Connection = require('velux-api').Connection;
*
* let conn = new Connection('velux-klf-12ab');
* conn.loginAsync('velux123')
* .then(() => {
* ... do some other stuff ...
* return conn.logoutAsync();
* })
* .catch((err) => { // always close the connection
* return conn.logoutAsync().reject(err);
* });
* ```
*
* @export
* @class Connection
*/
export declare class Connection implements IConnection {
private sckt?;
private klfProtocol?;
readonly host: string;
readonly CA: Buffer;
readonly fingerprint: string;
readonly connectionOptions?: ConnectionOptions;
/**
* Creates a new connection object that connect to the given host.
* @param {string} host Host name or IP address of the KLF-200 interface.
* @param {Buffer} [CA=ca] A buffer with a certificate of the certificate authority.
* Currently, the interface uses a self-signed certificate
* thus a certificate has to be provided for the CA.
* This parameter is optional and in case the certificate
* will be changed with subsequent firmware updates you can
* provide the matching certificate with this parameter.
* @param {string} [fingerprint=FINGERPRINT] The fingerprint of the certificate. This parameter is optional.
* @memberof Connection
*/
constructor(host: string, CA?: Buffer, fingerprint?: string);
/**
* Creates a new connection object that connect to the given host.
* @param host Host name or IP address of the KLF-200 interface.
* @param connectionOptions Options that will be provided to the connect method of the TLS socket.
*/
constructor(host: string, connectionOptions: ConnectionOptions);
/**
* Gets the [[KLF200SocketProtocol]] object used by this connection.
* This property has a value after calling [[loginAsync]], only.
*
* @readonly
* @memberof Connection
*/
get KLF200SocketProtocol(): KLF200SocketProtocol | undefined;
/**
* This method implements the login process without timeout.
* The [[loginAsync]] function wraps this into a timed promise.
*
* @private
* @param {string} password The password needed for login. The factory default password is velux123.
* @returns {Promise<void>} Returns a promise that resolves to true on success or rejects with the errors.
* @memberof Connection
*/
private _loginAsync;
/**
* Logs in to the KLF interface by sending the GW_PASSWORD_ENTER_REQ.
*
* @param {string} password The password needed for login. The factory default password is velux123.
* @param {number} [timeout=60] A timeout in seconds. After the timeout the returned promise will be rejected.
* @returns {Promise<void>} Returns a promise that resolves to true on success or rejects with the errors.
* @memberof Connection
*/
loginAsync(password: string, timeout?: number): Promise<void>;
/**
* Logs out from the KLF interface and closes the socket.
*
* @param {number} [timeout=10] A timeout in seconds. After the timeout the returned promise will be rejected.
* @returns {Promise<void>} Returns a promise that resolves to true on successful logout or rejects with the errors.
* @memberof Connection
*/
logoutAsync(timeout?: number): Promise<void>;
/**
* Sends a request frame to the KLF interface.
*
* @param {IGW_FRAME_REQ} frame The frame that should be sent to the KLF interface.
* @param {number} [timeout=10] A timeout in seconds. After the timeout the returned promise will be rejected.
* @returns {Promise<IGW_FRAME_RCV>} Returns a promise with the corresponding confirmation message as value.
* In case of an error frame the promise will be rejected with the error number.
* If the request frame is a command (with a SessionID) than the promise will be
* resolved by the corresponding confirmation frame with a matching session ID.
* @memberof Connection
*/
sendFrameAsync(frame: IGW_FRAME_REQ, timeout?: number): Promise<IGW_FRAME_RCV>;
/**
* Add a handler to listen for confirmations and notification.
* You can provide an optional filter to listen only to
* specific events.
*
* @param {Listener<IGW_FRAME_RCV>} handler Callback functions that is called for an event
* @param {GatewayCommand[]} [filter] Array of GatewayCommand entries you want to listen to. Optional.
* @returns {Disposable} Returns a Disposable that you can call to remove the handler.
* @memberof Connection
*/
on(handler: Listener<IGW_FRAME_RCV>, filter?: GatewayCommand[]): Disposable;
private _onFrameSent;
/**
* Add a handler to listen for sent frames.
* You can provide an optional filter to listen only to
* specific events.
*
* @param {Listener<IGW_FRAME_REQ>} handler Callback functions that is called for an event
* @param {GatewayCommand[]} [filter] Array of GatewayCommand entries you want to listen to. Optional.
* @returns {Disposable} Returns a Disposable that you can call to remove the handler.
* @memberof Connection
*/
onFrameSent(handler: Listener<IGW_FRAME_REQ>, filter?: GatewayCommand[]): Disposable;
private notifyFrameSent;
private keepAliveTimer?;
private keepAliveInterval;
/**
* Start a keep-alive timer to send a message
* at least every [[interval]] minutes to the interface.
* The KLF-200 interface will close the connection
* after 15 minutes of inactivity.
*
* @param {number} [interval=600000] Keep-alive interval in minutes. Defaults to 10 min.
* @memberof Connection
*/
startKeepAlive(interval?: number): void;
/**
* Stops the keep-alive timer.
* If not timer is set nothing happens.
*
* @memberof Connection
*/
stopKeepAlive(): void;
/**
* Sends a keep-alive message to the interface
* to keep the socket connection open.
*
* @private
* @returns {Promise<void>} Resolves if successful, otherwise reject
* @memberof Connection
*/
private sendKeepAlive;
/**
* Shifts the keep-alive timer to restart its counter.
* If no keep-alive timer is active nothing happens.
*
* @private
* @memberof Connection
*/
private shiftKeepAlive;
private initSocketAsync;
private socketClosedEventHandler;
private checkServerIdentity;
}