npm packaged modules

    iobroker.socketio

    6.3.3 • Public • Published

    Logo

    ioBroker socket.io

    Number of Installations Number of Installations NPM version Downloads

    NPM

    This adapter used by WEB applications and adapters to communicate with ioBroker using websockets and the socket.io protocol.

    Important Note: Since v4.0 of this adapter pure Websockets are used exclusively! Socket.io is no longer implemented by the socket.io library, but simulated via pure WebSockets!

    Users can use this adapter to connect their products to ioBroker via web sockets. Actually this adapter is e.g. used by Flot, Rickshaw, Vis and mobile to extract data from ioBroker.

    You can find in the example directory simple application that uses this interface to show some data.

    By using of socket.io interface user should understand the basics and concept of the system.

    It is useful to read about the structure of the objects too.

    This adapter uses Sentry libraries to automatically report exceptions and code errors to the developers. For more details and for information how to disable the error reporting see Sentry-Plugin Documentation! Sentry reporting is used starting with js-controller 3.0.

    Brief description of concept

    Object

    Object is description of data point or group. Group could content other data points in this case it called channel. If group consists of other channels in this case it called device.

    Object is meta information that describes data point and could content: max/min value, unit, name, default value, type of value, information for adapter for communication (e.g. ip address) and so on.

    State

    State is actual value of the data point and presented by javascript object:

    {
        val: VALUE, 
        ack: ACKNOWLEDGED, 
        ts: TIMESTAMP, // could be converted into time with "new Date(state.ts)" (In older version of js-controller - "new Date(state.ts * 1000)")
        lc: TIMESTAMP of last change, 
        from: ADAPTER_NAME, 
        q: QUALITY
    }
    

    States change itself very frequently in compare to the objects. (Normally objects should be changed once by creation and that's all)

    Acknowledgment

    Every state has the attribute "ack". It shows the direction of command.

    • If ack=false, it means some other adapter wants to control (write) this variable, so that command will be executed (e.g. light will be switched on).
    • If ack=true, it means that device informs about new value. (e.g. light was switched on manually or motion was detected)

    Example: we have some home automation adapter (HAA) that has one lamp connected under address haa.0.lamp1.

    • Lamp can be switched on manually with physical switch or via Wi-Fi with the help of HAA.
    • If vis wants to switch the lamp on via Wi-Fi it should set the new value with {value: true, ack: false}.
    • When the lamp is switched on it is normally inform HAA about new state and the value should be immediately overwritten with {value: true, ack: true}.
    • If the lamp is switched off manually via physical switch it informs HAA about new state with {value: false, ack: true}.

    Quality

    Every data point has an attribute q - quality.

    Usage

    It is suggested to use example/conn.js for communication.

    After inclusion of conn.js file the global object servConn could be used to establish the communication with socketio adapter.

    servConn object has hollowing methods:

    init

    • function (connOptions, connCallbacks, objectsRequired)

    connOptions - is optional parameter:

    connOptions = {
        name:          'name of the connection', // optional - default 'vis.0', used to distinguish connections in socket-io adapter.
        connLink:      'http://localhost:8084',  // optional - URL of the socket.io adapter. By default it is same URL where the WEB server is. 
        socketSession: ''                        // optional - default 'nokey', and used by authentication
    };
    

    You can pass these parameters by defining the global variables before call of "init" too:

    var socketUrl      = 'http://localhost:8084';  // is connOptions.connLink
    var socketSession  = '';                       // is connOptions.socketSession
    servConn.namespace = 'myapp';                  // is connOptions.name
    

    connCallbacks - object with callbacks:

    connCallbacks = {
        onConnChange:   function (isConnected) {}, // optional - called if connection state changed.
        onObjectChange: function (id, obj)     {}, // optional - called if content of some object is changed, new object created or object was deleted (obj = null)
        onUpdate:       function (id, state)   {}, // optional - called if state of some object is changed, new state for object is created or state was deleted (state = null)
        onError:        function (error)       {}  // optional - called if some error occurs
    };
    

    setState

    • function (pointId, value, callback)

    set new value of some data point.

    E.g. servConn.setState('adapter.0.myvalue', true) writes {val: true, ack: false} into adapter.0.myvalue.

    • pointId - is ID of the state, like adapter.0.myvalue,
    • value - new value of the state, could be simple value (string, number, boolean) or object like {val: newValue, ack: false, q: 0}. In case if used simple value, "ack" will be set to "false".
    • callback - function (error) {} - called when the writing of new value into DB is performed (not when the device was controlled).

    getStates

    • function (IDs, callback)

    get the states of more than one state. This command normally is called after the connection is established to get the actual states of used data points.

    • IDs - pattern or array with IDs. Could be omitted to get all states. Patterns could have wildcards, like: '.STATE', 'haa.0.'
    • callback - function (error, states) {} - states is object like {'id1': 'state1', 'id2': 'state2', ...}. stateX are objects with the structure described above.

    httpGet

    • function (url, callback)

    calls this URL from PC, where socketio adapter runs.

    • url - is address to call.
    • callback - function (data) {} - result of the request (html body).

    logError

    • function (errorText)

    writes error message into controller's log.

    getConfig

    • function (callback)

    reads controller configuration like language, temperature units, point or comma delimiter in floats, date format.

    • callback - function (err, config) {} - config looks like:
    {
      "_id": "system.config",
      "type": "config",
      "common": {
        "name":             "System configuration",
        "language":         "de",
        "tempUnit":         "°C",
        "currency":         "€",
        "dateFormat":       "DD.MM.YYYY",
        "isFloatComma":     true,
        "licenseConfirmed": true,
        "activeRepo":       "fast-online",
        "diag":             "extended",
        "defaultHistory":   ""
      }
    }
    

    getObject

    • function (id, callback)

    read specific object from DB. With this function the meta information of some object could be read.

    • id - id of the state, like "haa.0.light1",
    • callback - function (error, obj) - obj looks like:
    {
      "_id": "haa.0.light1",
      "type": "state",
      "common": {
        "def": false,
        "type": "boolean",
        "read": false,
        "write": true,
        "role": "switch",
        "name": "light in floor"
      },
      "native": {
        "CONTROL": "BUTTON.LONG",
        "DEFAULT": false,
        "FLAGS": 1,
        "ID": "PRESS_LONG",
        "MAX": true,
        "MIN": false,
        "OPERATIONS": 6,
        "TAB_ORDER": 1,
        "TYPE": "ACTION",
        "UNIT": ""
      },
      "enums": ['enum.rooms.floor'],
      "acl": {
        "object": 1638,
        "state": 1638
      }
    }  
    

    getObjects

    • function (callback)

    read all objects from DB.

    • callback - function (error, objs) - objs looks like: {'id1': 'object1', 'id2': 'object2', ...}

    readDir

    • function (dirName, callback)

    reads files and directories in specified directory.

    Files are stored in DB (or similar) and normally should not be accessed directly. File name consist of path, filename and file extension, like "/mobile.0/data/fileName.txt".

    • dirName - name of the directory like /mobile.0/data
    • callback - function (error, list) - list looks like:
    [
        {
            file:       'file1.txt',
            stats:      {
                          mode: 33188,
                          size: 527,
                          atime: Mon, 10 Oct 2011 23:24:11 GMT,
                          mtime: Mon, 10 Oct 2011 23:24:11 GMT,
                          ctime: Mon, 10 Oct 2011 23:24:11 GMT,
                          birthtime: Mon, 10 Oct 2011 23:24:11 GMT
                        },
            isDir:      false,
            modifiedAt: timeInMs, // new Date().getTime()
            createdAt:  timeInMs, // new Date().getTime()
        },
        {
            file:       'main',
            stats:      {
                          mode: 33188,
                          atime: Mon, 10 Oct 2011 23:24:11 GMT,
                          mtime: Mon, 10 Oct 2011 23:24:11 GMT,
                          ctime: Mon, 10 Oct 2011 23:24:11 GMT,
                          birthtime: Mon, 10 Oct 2011 23:24:11 GMT
                        },
            isDir:      true,
            modifiedAt: timeInMs, // new Date().getTime()
            createdAt:  timeInMs, // new Date().getTime()
        },
        ...
    ]                
    

    mkdir

    • function (dirName, callback)

    • callback - function (error) {}

    unlink

    • function (name, callback)

    deletes file or directory. Directory must be empty to be deleted.

    • dirName - name of the directory or file like /mobile.0/data.
    • callback - function (error) {}

    readFile

    • function (filename, callback)

    • callback - function (error, fileData, mimeType)

    readFile64

    • function (filename, callback)

    • callback - function (error, data) - data is {mime: mimeType, data: base64data}

    writeFile

    • function (filename, data, mode, callback)

    • callback - function (error) {}

    writeFile64

    • function (filename, data, mode, callback)

    • callback - function (error) {}

    renameFile

    • function (oldName, newName, callback)

    • callback - function (error) {}

    getHistory

    • function (instance, options, callback)

    • callback - function (error, data, step, sessionId) {}

    requireLog

    • function (isRequire, callback)

    activates/deactivates log receiving for this socket.

    • callback - function (error) {}

    authEnabled

    • function ()

    reads if the authentication is enabled and which user is logged in

    • callback - function (authEnabled, currentUser) {}

    If authentication is enabled, so current logged-in user will be returned, if auth is disabled, so the default user "running as" will be returned.

    Tuning Web-Sockets

    On some web-sockets clients there is performance problem with communication. Sometimes this issue is due to fallback of socket.io communication on long polling mechanism. You can set option Force Web-Sockets to force using only web-sockets transport.

    Changelog

    6.3.3 (2022-12-22)

    • (bluefox) used new socket-classes

    6.3.1 (2022-11-27)

    • (bluefox) Added fileChange event

    6.2.0 (2022-11-08)

    • (Apollon77) Prepare for future js-controller versions
    • (bluefox) Function getObjects for web was extended by devices, channels and enums

    6.1.10 (2022-08-24)

    • (bluefox) Caught error by subscribe

    6.1.8 (2022-07-08)

    • (bluefox) Corrected getAdapterInstances method

    6.1.7 (2022-06-20)

    • (bluefox) Allowed to overload the system language

    6.1.6 (2022-06-20)

    • (bluefox) Allowed to run socket.io behind proxy

    6.1.5 (2022-06-09)

    • (bluefox) Do not show requireLog message

    6.1.4 (2022-05-27)

    • (Apollon77) Fixed crash cases reported by Sentry

    6.1.3 (2022-05-20)

    • (bluefox) Corrected "force web-sockets" mode

    6.1.1 (2022-05-20)

    • (bluefox) Reverted socket.io to V2

    6.0.2 (2022-05-20)

    6.0.1 (2022-05-19)

    5.0.2 (2022-05-19)

    • (bluefox) Hide warn messages

    5.0.1 (2022-05-16)

    • (bluefox) Used common sockets (could be buggy)

    4.2.0 (2022-03-27)

    • (bluefox) Added log socket command

    4.1.5 (2022-03-20)

    • (Apollon77) make sure patterns are handled as strings on subscribe/unsubscribe
    • (Apollon77) when getHistory is called with instance as string correct the data into an object

    4.1.4 (2022-02-16)

    • (bluefox) Added unlink and rename to web functions

    4.1.2 (2022-02-13)

    • (bluefox) Corrected the connection indication

    4.1.0 (2022-01-31)

    • (bluefox) Update socket.io library to 2.4.1
    • (bluefox) Used json config for settings

    3.1.5 (2021-10-22)

    • (foxriver76) make error logging on failed authentication more specific
    • (foxriver76) "request" was replaced by "axios"

    3.1.4 (2021-01-13)

    • (Apollon77) Define instanceObject "connected" to prevent warning with js-controller 3.2

    3.1.3 (2021-01-12)

    • (Apollon77) fix socketio dependency

    3.1.2 (2021-01-09)

    • (bluefox) Support of new Let's Encrypt (only with js-controller 3.2.x)

    3.0.13 (2020-08-21)

    • (bluefox) Added getAdapterName method

    3.0.12 (2020-07-27)

    • (Apollon77) socket.io pingTimeout and pinInterval increased to prevent too fast reconnections and bigger visualizations

    3.0.11 (2020-07-23)

    • (Apollon77) make sure web adapter gets restarted on socketio adapter upgrade

    3.0.10 (2020-07-16)

    • (Apollon77) Error caught when trying to write an empty base64 value into a file (Sentry )

    3.0.9 (2020-06-11)

    • (Apollon77) optimize error handling on webserver initialization again

    3.0.8 (2020-06-10)

    • (Apollon77) Make sure adapter does not crash if getHttp is called with an invalid URL (Sentry IOBROKER-WEB-R)

    3.0.7 (2020-05-04)

    • (Apollon77) webserver initialization optimized again to prevent errors with invalid certificates

    3.0.6 (2020-04-30)

    • (bluefox) errors on webserver initialization are handled properly

    3.0.5 (2020-04-23)

    • (bluefox) Caught the web server errors

    3.0.4 (2020-04-23)

    • fix crash reason when server closes (Sentry IOBROKER-SOCKETIO-2/3/4/5)

    3.0.3 (2020-04-16)

    • (Apollon77) Remove usage of deprecated object methods; prevent js-controller 3.0 warnings
    • (Apollon77) Add Sentry error reporting

    3.0.2 (2020-03-07)

    • (bluefox) Unload of adapter was corrected

    3.0.1 (2020-02-23)

    • (Apollon77) Workaround for socket.io bug #3555 added to make sure always the correct client files are delivered

    3.0.0 (2020-01-15)

    • (Apollon77) upgrade all dependencies, especially socketio to current version! This might break ipad 1/2 devices

    2.1.2 (2019-09-28)

    • (Apollon77) optimize shutdown for compact mode

    2.1.1 (2018-06-09)

    • (bluefox) Used socket.io Version 1.7.2
    • (bluefox) Fix authentication problem

    2.1.0 (2018-05-04)

    • (bluefox) Used socket.io Version 1.7.4

    2.0.1 (2018-02-28)

    • (bluefox) Dropped support of old browsers. Please do not update if you have iPad 1 and so on.

    1.9.0 (2018-01-14)

    • (bluefox) Ready for admin3

    1.8.7 (2017-11-29)

    • (bluefox) Tune cloud work

    1.8.5 (2017-10-22)

    • (bluefox) Escape [] in subscriptions

    1.8.4 (2017-10-16)

    • (bluefox) Check callback validity

    1.8.3 (2017-10-09)

    • (bluefox) Allow authentication via URL

    1.8.2 (2017-09-20)

    • (bluefox) Fix cmdExec command

    1.8.1 (2017-09-13)

    • (bluefox) Fix user access rights for sendToHost

    1.8.0 (2017-08-06)

    • (bluefox) Support the access to admin via iobroker.pro

    1.7.5 (2017-05-24)

    • (bluefox) fix error if subscribe is empty

    1.7.4 (2017-01-04)

    • (bluefox) fix error with authentication

    1.7.3 (2016-11-13)

    • (bluefox) support of socket extensions

    1.7.2 (2016-11-06)

    • (bluefox) Fix unsubscribe of states

    1.7.1 (2016-10-11)

    • (bluefox) Fix authentication for app

    1.7.0 (2016-08-30)

    • (bluefox) compatible only with new admin

    1.6.1 (2016-08-29)

    • (bluefox) fix error by checking user name

    1.6.0 (2016-08-27)

    • (bluefox) support of letsencrypt certificates

    1.5.4 (2016-08-26)

    • (bluefox) fix error in socket.js

    1.5.3 (2016-08-14)

    • (bluefox) support of force only web sockets transport

    1.5.2 (2016-07-06)

    • (bluefox) support of chained certificates

    1.5.1 (2016-06-28)

    • (bluefox) add sendToHost command

    1.5.0 (2016-06-17)

    • (bluefox) preparations for cloud

    1.4.1 (2016-05-13)

    • (bluefox) change getHistory function

    1.4.0 (2016-04-24)

    • (bluefox) encode json files

    1.3.0 (2016-03-17)

    • (bluefox) rename files

    1.2.3 (2015-12-24)

    • (bluefox) support of authentication over URL

    1.2.2 (2015-12-09)

    • (bluefox) remove unused parameter "cache"

    1.2.0 (2015-11-15)

    • (bluefox) add version compatibility check

    1.1.0 (2015-11-14)

    • (Smiling_Jack) add getHistory

    1.0.0 (2015-09-30)

    • (bluefox) stop adapter before update

    0.4.5 (2015-08-11)

    • (bluefox) update packets

    0.4.4 (2015-07-07)

    • (bluefox) extend writeFile with mode

    0.4.3 (2015-07-06)

    • (bluefox) add chmodFile

    0.4.1 (2015-06-13)

    • (bluefox) add default ttl
    • (bluefox) enable run from "web" and add permissions check

    0.4.0 (2015-06-13)

    • (bluefox) add permissions support

    0.3.1 (2015-05-19)

    • (bluefox) support of subscribe on objectChanged

    0.3.0 (2015-04-23)

    • (bluefox) enable security

    0.2.3 (2015-03-07)

    • (bluefox) extend getStates to support list of objects

    0.2.2 (2015-02-14)

    • (bluefox) fix error with objectChanged event

    0.2.0 (2015-01-16)

    • (bluefox) make socket usable as module

    0.1.6 (2015-01-08)

    • (bluefox) support of subscribe for different sockets. Support of socket names. Diagnostic info in socket.0.connected

    0.1.5 (2015-01-07)

    • (bluefox) fix error with update of states and objects

    0.1.4 (2015-01-06)

    • (bluefox) support of file manager in vis

    0.1.3 (2015-01-02)

    • (bluefox) enable adapter by default

    0.1.2 (2015-01-02)

    • (bluefox) add "request" module to package.json

    0.1.1 (2015-01-02)

    • (bluefox) enable npm install

    0.1.0 (2014-12-28)

    • (bluefox) support of read/write files

    0.0.5 (2014-12-19)

    • (bluefox) support of setObjects command

    0.0.4 (2014-12-10)

    • (bluefox) support of https sockets

    0.0.3 (2014-12-05)

    • (bluefox) support of https sockets

    0.0.2 (2014-11-24)

    • (bluefox) fix error by start

    0.0.1 (2014-10-10)

    • (bluefox) authentication works

    License

    The MIT License (MIT)

    Copyright (c) 2014-2022 bluefox dogafox@gmail.com

    Keywords

    Install

    npm i iobroker.socketio

    DownloadsWeekly Downloads

    2,717

    Version

    6.3.3

    License

    MIT

    Unpacked Size

    222 kB

    Total Files

    22

    Last publish

    Collaborators

    • foxriver76
    • iobluefox
    • bluefox
    • apollon77
    • ldittmar
    • alcalzone