Have ideas to improve npm?Join in the discussion! »

    homematic-js-xmlapi
    TypeScript icon, indicating that this package has built-in type declarations

    0.8.1 • Public • Published

    homematic-js-xmlapi

    NPM

    Release npm version Downloads Issues License

    A nodejs module for connecting a Homematic CCU with an installed XML-API addon.

    The module addresses the XML API and provides the required interfaces and data types in JS. It is released as npm module under homematic-js-xmlapi

    Interfaces currently implemented

    • devicelist.cgi
    • state.cgi
    • statelist.cgi
    • statechange.cgi
    • sysvar.cgi
    • sysvarlist.cgi
    • version.cgi

    Usage

    Install

    npm install homematic-js-xmlapi
    

    Basic Usage

    import { XmlApi, DeviceManager } from 'homematic-js-xmlapi';
     
    // initialise the API Connection
    const xmlApi = new XmlApi("192.168.0.10", 80);
    const deviceMgr = new DeviceManager();
     
    // get all devices 
    xmlApi.getDeviceList().then((deviceList) => {
      if (deviceList) deviceMgr.updateDeviceList(deviceList);
    });
     
    // get single state value 
    xmlApi.getState('1481').then((deviceList) => {
      if (deviceList) deviceMgr.updateDeviceList(deviceList);
    });

    Example of the update implementation for receiving the data without using DeviceManager

    const deviceMap:Map<string, Device> = new Map();
     
    function updateDeviceList(deviceList: Device[]) {
        for (let device of deviceList) {
            if (deviceMap.has(device.iseId)) {
                device.updateValues(device);
            } else {
                deviceMap.set(device.iseId, device);
            }
        }
    }

    More Examples

    More examples and details in exampe.ts

    You can also check my own project for detailed usage example and inspiration https://github.com/jenszech/hm-node-runner

    Dokumentation

    Klassen

    XmlApi

    The XmlApi class provides the XML connector for the homematic xml addon. The class provides a separate function for each call, which returns a corresponding JS data object.

    Constructor usage

    import {XmlApi} from "homematic-js-xmlapi";
    const xmlApi = new XmlApi("1.1.1.1", 80);

    Api functions

    import { DeviceManager } from 'homematic-js-xmlapi';
     
    // Get XML Addon Verion
    // return Promise<number | null>
    xmlApi.getVersion().then((version) => {
      console.log('XML Addon version: ', version);
    });
     
    // Get all devices ...
    // return Promise<Device[] | null>
    xmlApi.getDeviceList().then((deviceList) => {
      if (deviceList) deviceMgr.updateDeviceList(deviceList);
    });
     
    // Get a single device state ... 
    // return Promise<Device[] | null>
    xmlApi.getState('1481').then((deviceList) => {
      if (deviceList) deviceMgr.updateDeviceList(deviceList);
    });
     
    // Get all device states ...
    // return Promise<Device[] | null> 
    xmlApi.getStateList().then((deviceList) => {
      if (deviceList) deviceMgr.updateDeviceList(deviceList);
    });
     
    // Get a single SystemVariable value ... 
    // return Promise<SystemVariable[] | null>
    xmlApi.getSysVar('7264').then((sysVarList) => {
      if (deviceList) deviceMgr.updateDeviceList(deviceList);
    });
     
    // Get all SystemVariable values ...
    // return Promise<SystemVariable[] | null> 
    xmlApi.getSysVarList().then((sysVarList) => {
      if (deviceList) deviceMgr.updateDeviceList(deviceList);
    });

    DeviceManager

    Constructor usage

    import { DeviceManager } from 'homematic-js-xmlapi';
    const devMgr = new DeviceManager();

    Api functions

    // Add or Update a single Device
    // Parameter: Device
    devMgr.updateDevice(device);
     
    // Add or Update a list of Devices
    // Parameter: Device[]
    devMgr.updateDeviceList(deviceList);
     
    // Get actual count of known devices
    devMgr.mapCount();
     
    // Get the actual cached device with given device name
    // Parameter: name: string 
    // return Device | null
    devMgr.getDeviceByName(name);
     
    // Get the actual cached Channel with given Channel name
    // Parameter: name: string 
    // return Channel | null
    devMgr.getDeviceByName(name);
     
    // Get the actual cached Datapoint with given DataType from given Channel
    // Parameter: channel : Channel
    // Parameter: type : DataType 
    // return Channel | null
    devMgr.getValueByTyp(name);
     
    // print a complete list of all kown devices to console 
    devMgr.printDeviceList
     
    // print a complete list of all kown devices grouped and counted by deviceType to console
    devMgr.printDeviceTypes();

    SystemVariableManager

    Constructor usage

    import { SystemVariableManager } from 'homematic-js-xmlapi';
    const sysMgr = new SystemVariableManager();

    Api functions

    // Add or Update a single Variable
    // Parameter: SystemVariable
    sysMgr.updateDevice(sysVar);
     
    // Add or Update a list of variables
    // Parameter: SystemVariable[]
    sysMgr.updateDeviceList(sysVarList);
     
    // Get actual count of known variables
    sysMgr.mapCount();
     
    // Get the actual cached device with given variable name
    // Parameter: name: string 
    // return SystemVariable | null
    sysMgr.getVariableByName(name);
     
    // print a complete list of all kown variables to console 
    sysMgr.printSysVarList();

    Data Object

    The library automatically converts the XML response into different JS data objects. The following data types are provided:

    import { Device, Channel, DataPoint, SystemVariable } from 'homematic-js-xmlapi'
    import { DataType, ValueType } from 'homematic-js-xmlapi'  //only if needed
    Device {
      name: string;
      iseId: string;
      unreach: boolean;
      stickyUnreach: boolean;
      configPending: boolean;
      address: string | null;
      deviceType: string | null;
      channel: Map<string, Channel> = new Map();
    }
    Channel {
       name: string;
        iseId: string;
        address: string | null;
        dataPoint: Map<DataType, DataPoint> = new Map();
    }
    DataPoint {
      name: string;
      iseId: string;
      type: DataType;
      value: string;
      valueType: ValueType;
      timestamp: Date | null;
    }
    SystemVariable {  
      name: string;
      iseId: string;
      value: string | number | boolean | null;
      valueList: string;
      valueType: number;
      timestamp: Date | null;
    }

    Development and build pipeline

    Release a new version

    npm version major|minor|patch
    npm publish
    

    Further documentation

    Homematic XML-API CCU Addon
    https://github.com/jens-maus/XML-API

    Step by step: Building and publishing an NPM Typescript package.
    https://itnext.io/step-by-step-building-and-publishing-an-npm-typescript-package-44fe7164964c

    License

    See the LICENSE file for license rights and limitations (MIT).

    Install

    npm i homematic-js-xmlapi

    DownloadsWeekly Downloads

    1

    Version

    0.8.1

    License

    MIT

    Unpacked Size

    79.4 kB

    Total Files

    45

    Last publish

    Collaborators

    • avatar