@iobroker/socket-classes

This library is used at least for the following adapters:

• iobroker.admin
• iobroker.cloud
• iobroker.socketio
• iobroker.ws
• iobroker.rest-api
• iobroker.iot

Usage as admin

const TTL_SEC      = 3600;

const SocketAdmin  = require('@iobroker/socket-classes').SocketAdmin;
const ws           = require('@iobroker/ws-server');
const session      = require('express-session');
const utils 	   = require('@iobroker/adapter-core'); // Get common adapter utils
const AdapterStore = require(utils.controllerDir + '/lib/session.js')(session, TTL_SEC);

const store = new AdapterStore({adapter});

const io = new SocketAdmin(adapter.config, adapter, objects);
io.start(
    server,
    ws,
    {
        userKey: 'connect.sid',
        store,
        secret: adapter.config.secret
    }
);

// subscribe on all object changes
io.subscribe('objectChange', '*');


// later
io.close();

Usage as socket (ws or socketio)

const TTL_SEC      = 3600;

const ws           = require('@iobroker/ws-server');
const SocketWS     = require('@iobroker/socket-classes').SocketCommon;
const session      = require('express-session');
const utils 	   = require('@iobroker/adapter-core'); // Get common adapter utils
const AdapterStore = require(utils.controllerDir + '/lib/session.js')(session, TTL_SEC);

const store = new AdapterStore({adapter});

const settings = adapter.config;
settings.crossDomain = true;
settings.ttl = settings.ttl || TTL_SEC;

const io = new SocketWS(settings, adapter);
io.start(server.server, ws, {userKey: 'connect.sid', checkUser, store, secret: adapter.config.secret});


// later
io.close();

GUI subscribes

clientSubscribe and clientUnsubscribe deliver a message to an adapter instance and therefore require the same permission as sendTo: other.sendto. Users without it receive a permission error.

GUI client can send to desired instance the subscribe message

    socket.emit('clientSubscribe', 'cameras.0', 'startCamera', { width: 640, height: 480 }, result => console.log('Started: ' + result));

The instance 'cameras.0' will receive message clientSubscribe with information who want to receive messages.

adapter.on('message', obj => {
    if (obj?.command === 'clientSubscribe') {
        if (obj?.message.type && obj.message.type.startsWith('startCamera/')) {
            const [, camera] = obj.message.type.split('/');
            // start camera with obj.message.data
            // ...
            
            // inform GUI that camera is started
            adapter.sendTo(obj.from, obj.command, {result: true}, obj.callback);
            this.subscribes = this.subscribes || [];
            this.subscribes.push({sid: obj.message.sid, from: obj.from, type: obj.message.type, camera});
        }
    } else if (obj?.command === 'clientUnsubscribe' || obj?.command === 'clientSubscribeError') {
        if (obj?.message.type && obj.message.type.startsWith('startCamera/')) {
            const [, camera] = obj.message.type.split('/');
            if (this.subscribes) {
                const pos = this.subscribes.findIndex(s => s.sid === obj.message.sid && s.from === obj.from && s.type === obj.message.type);
                if (pos !== -1) {
                    this.subscribes.splice(pos, 1);

                    // stop camera
                    // ...
                }
            }
        }
    }
});

and after that the client will receive messages from instance

function sendImage(camera, data) {
    this.subscribes.forEach(it => {
        if (it.camera !== camera) {
            return;
        }
        // send image to GUI
        adapter.sendTo(it.from, 'im', {m: it.type, s: it.sid, d: data});
    });
}

Web Methods

List of commands

• authenticate
• updateTokenExpiration
• error
• log
• checkFeatureSupported
• getHistory
• httpGet
• sendTo
• sendToHost
• authEnabled
• logout
• listPermissions
• getUserPermissions
• getVersion
• getAdapterName
• clientSubscribe
• clientUnsubscribe
• getCompactSystemConfig
• getAdapterInstances
• getObject
• getObjects
• getAllObjects
• subscribeObjects
• unsubscribeObjects
• getObjectView
• setObject
• delObject
• getStates
• getForeignStates
• getState
• setState
• getBinaryState
• setBinaryState
• subscribe
• subscribeStates
• unsubscribe
• unsubscribeStates
• readFile
• readFile64
• writeFile64
• writeFile
• unlink
• deleteFile
• deleteFolder
• renameFile
• rename
• mkdir
• readDir
• chmodFile
• chownFile
• fileExists
• subscribeFiles
• unsubscribeFiles

Commands

authenticate(callback)

Wait till the user is authenticated. As the user authenticates himself, the callback will be called

• callback (isUserAuthenticated: boolean, isAuthenticationUsed: boolean) => void) => void: Callback (isUserAuthenticated: boolean, isAuthenticationUsed: boolean) => void

updateTokenExpiration(accessToken, callback)

After the access token is updated, this command must be called to update the session (Only for OAuth2)

• accessToken string: New access token
• callback (error: string | undefined | null, success?: boolean) => void) => void: Callback (error: string | undefined | null, success?: boolean) => void

error(error)

Write error into ioBroker log

• error Error | string: Error object or error text

log(text, level)

Write log entry into ioBroker log

• text string: log text
• level ioBroker.LogLevel: one of ['silly', 'debug', 'info', 'warn', 'error']. The default is 'debug'.

checkFeatureSupported(feature, callback)

Check if the same feature is supported by the current js-controller

• feature SupportedFeature: feature name like CONTROLLER_LICENSE_MANAGER
• callback (error: string | Error | null | undefined, isSupported?: boolean) => void) => void: callback (error: string | Error | null | undefined, isSupported: boolean) => void

getHistory(id, options, callback)

Get the history data from the specific instance

• id string: object ID
• options ioBroker.GetHistoryOptions: History options
• callback (error: string | Error | null | undefined, result: ioBroker.GetHistoryResult) => void) => void: callback (error: string | Error | null | undefined, result: ioBroker.GetHistoryResult) => void

httpGet(url, callback)

Read content of HTTP(s) page server-side (without CORS and stuff)

• url string: Page URL
• callback (error: Error | null | undefined | string, result?: {status: number; statusText: string}, data?: string) => void: callback (error: Error | null, result?: { status: number; statusText: string }, data?: string) => void

sendTo(adapterInstance, command, message, callback)

Send the message to specific instance

• adapterInstance string: instance name, e.g. history.0
• command string: command name
• message any: the message is instance-dependent
• callback (result: any) => void) => void: callback (result: any) => void

sendToHost(host, command, message, callback)

Send a message to the specific host. Host can answer to the following commands: cmdExec, getRepository, getInstalled, getInstalledAdapter, getVersion, getDiagData, getLocationOnDisk, getDevList, getLogs, getHostInfo, delLogs, readDirAsZip, writeDirAsZip, readObjectsAsZip, writeObjectsAsZip, checkLogging, updateMultihost.

• host string: Host name. With or without 'system.host.' prefix
• command * 'shell' | 'cmdExec' | 'getRepository' | 'getInstalled' | 'getInstalledAdapter' | 'getVersion' | 'getDiagData' | 'getLocationOnDisk' | 'getDevList' | 'getLogs' | 'getLogFile' | 'getLogFiles' | 'getHostInfo' | 'getHostInfoShort' | 'delLogs' | 'readDirAsZip' | 'writeDirAsZip' | 'readObjectsAsZip' | 'writeObjectsAsZip' | 'checkLogging' | 'updateMultihost' | 'upgradeController' | 'upgradeAdapterWithWebserver' | 'getInterfaces' | 'upload' | 'rebuildAdapter' | 'readBaseSettings' | 'writeBaseSettings' | 'addNotification' | 'clearNotifications' | 'getNotifications' | 'updateLicenses' | 'upgradeOsPackages' | 'restartController' | 'sendToSentry'*: Host command
• message any: the message is command-specific
• callback (result: {error?: string; result?: any}) => void) => void: callback (result: { error?: string; result?: any }) => void

authEnabled(callback)

Ask server is authentication enabled, and if the user authenticated

• callback (isUserAuthenticated: boolean | Error | string, isAuthenticationUsed: boolean) => void) => void: callback (isUserAuthenticated: boolean | Error | string, isAuthenticationUsed: boolean) => void

logout(callback)

Logout user

• callback ioBroker.ErrorCallback: callback (error?: Error) => void

listPermissions(callback)

List commands and permissions

• callback (permissions: Record< string, {type: 'object' | 'state' | 'users' | 'other' | 'file' | ''; operation: SocketOperation} >) => void: callback (permissions: Record<string, { type: 'object' | 'state' | 'users' | 'other' | 'file' | ''; operation: SocketOperation }>) => void

getUserPermissions(callback)

Get user permissions

• callback (error: string | null | undefined, userPermissions?: SocketACL | null) => void) => void: callback (error: string | null | undefined, userPermissions?: SocketACL | null) => void

getVersion(callback)

Get the adapter version. Not the socket-classes version!

• callback (error: string | Error | null | undefined, version: string | undefined, adapterName: string) => void: callback (error: string | Error | null | undefined, version: string | undefined, adapterName: string) => void

getAdapterName(callback)

Get adapter name: "iobroker.ws", "iobroker.socketio", "iobroker.web", "iobroker.admin"

• callback (error: string | Error | null | undefined, adapterName: string) => void) => void: callback (error: string | Error | null | undefined, version: string | undefined, adapterName: string) => void

clientSubscribe(targetInstance, messageType, data, callback)

Client subscribes to specific instance's messages. Client informs a specific instance about subscription on its messages. After subscription, the socket will receive "im" messages from the desired instance The target instance MUST acknowledge the subscription and return result

• targetInstance string: Instance name, e.g., 'cameras.0'
• messageType string: Message type, e.g., 'startRecording/cam1'
• data any: Optional data object, e.g., {width: 640, height: 480}
• callback (error: string | null | Error | undefined, result?: {accepted: boolean; heartbeat?: number; error?: string}) => void: Callback (error: string | null, result?:{ accepted: boolean; heartbeat?: number; error?: string; }) => void

clientUnsubscribe(targetInstance, messageType, callback)

Client unsubscribes from specific instance's messages. The target instance MUST NOT acknowledge the un-subscription

• targetInstance string: Instance name, e.g., 'cameras.0'
• messageType string: Message type, e.g., 'startRecording/cam1'
• callback (error: string | null | Error | undefined) => void) => void: Callback (error: string | null) => void

getCompactSystemConfig(callback)

Get the system configuration in a compact form to save bandwidth.

• callback (error: string | null | Error | undefined, systemConfig?: {common: ioBroker.SystemConfigCommon; native?: {secret: string; vendor?: any}}) => void: - Callback function (error: string | null, systemConfig?: { common: any; native?: { secret: string } }) => void

getAdapterInstances(adapterName, callback)

Read all instances of the given adapter, or all instances of all adapters if adapterName is not defined

• adapterName string | undefined: adapter name, e.g. history. To get all instances of all adapters, just place here "".
• callback (error: null | undefined | Error | string, instanceList?: ioBroker.InstanceObject[]) => void) => void: callback (error: null | undefined | Error | string, instanceList?: ioBroker.InstanceObject[]) => void

Objects

getObject(id, callback)

Get one object.

• id string: Object ID
• callback (error: Error | undefined | string | null, obj?: ioBroker.Object) => void) => void: Callback (error: string | null, obj?: ioBroker.Object) => void

getObjects(list, callback)

Get all objects that are relevant for the web: all states and enums with rooms. This is a non-admin version of "all objects" and will be overloaded in admin

• list string[] | null: Optional list of IDs
• callback (error: Error | undefined | string | null, objs?: Record<string, ioBroker.Object>) => void) => void: Callback (error: string | null, objs?: Record<string, ioBroker.Object>) => void

getAllObjects(callback)

Get all objects that are relevant for the web: all states and enums with rooms.

• callback (error: null | undefined | Error | string, result?: Record<string, ioBroker.Object>) => void) => void: - Callback function (error: string | null, objects?: Record<string, ioBroker.Object>) => void

subscribeObjects(pattern, callback)

Subscribe to object changes by pattern. The events will come as 'objectChange' events to the socket.

• pattern string | string[]: Pattern like system.adapter.* or array of IDs like ['system.adapter.admin.0.memRss', 'system.adapter.admin.0.memHeapTotal']
• callback (error: Error | undefined | string | null) => void) => void: Callback (error: string | null) => void

unsubscribeObjects(pattern, callback)

Unsubscribe from object changes by pattern.

• pattern string | string[]: Pattern like system.adapter.* or array of IDs like ['system.adapter.admin.0.memRss', 'system.adapter.admin.0.memHeapTotal']
• callback (error: string | null | Error | undefined) => void) => void: Callback (error: string | null) => void

getObjectView(design, search, params, callback)

Get a view of objects. Make a query to the object database.

• design string: Design name, e.g., 'system' or other designs like custom, but it must exist object _design/custom. To 99,9% use system.
• search string: Search name, object type, like state, instance, adapter, host, ...
• params {startkey?: string; endkey?: string; depth?: number}: Parameters for the query, e.g., {startkey: 'system.adapter.', endkey: 'system.adapter.\u9999', depth?: number}
• callback (error: string | null | Error | undefined, result?: {rows: {id: string; value: ioBroker.Object & {virtual: boolean; hasChildren: number;};}[];}) => void: Callback (error: string | null, result?: { rows: Array<GetObjectViewItem> }) => void

setObject(id, obj, callback)

Set an object.

• id string: Object ID
• obj ioBroker.Object: Object to set
• callback (error: string | null | Error | undefined) => void) => void: Callback (error: string | null) => void

delObject(id, _options, callback)

Delete an object. Only deletion of flot and fullcalendar objects is allowed

• id string: Object ID, like 'flot.0.myChart'
• _options any: Options for deletion. Ignored
• callback (error: string | null | Error | undefined) => void) => void: Callback (error: string | null) => void

States

getStates(pattern, callback)

Get states by pattern of current adapter

• pattern string | string[] | undefined: optional pattern, like system.adapter.* or array of state IDs. If the pattern is omitted, you will get ALL states of current adapter
• callback (error: null | undefined | Error | string, states?: Record<string, ioBroker.State>) => void) => void: callback (error: null | undefined | Error | string, states?: Record<string, ioBroker.State>) => void

getForeignStates(pattern, callback)

Same as getStates

• pattern string | string[]: pattern like system.adapter.* or array of state IDs
• callback (error: null | undefined | Error | string, states?: Record<string, ioBroker.State>) => void) => void: callback (error: null | undefined | Error | string, states?: Record<string, ioBroker.State>) => void

getState(id, callback)

Get a state by ID

• id string: State ID, e.g. system.adapter.admin.0.memRss
• callback (error: null | undefined | Error | string, state?: ioBroker.State) => void) => void: Callback (error: null | undefined | Error | string, state?: ioBroker.State) => void

setState(id, state, callback)

Set a state by ID

• id string: State ID, e.g. system.adapter.admin.0.memRss
• state ioBroker.SettableState: State value or object, e.g. {val: 123, ack: true}
• callback (error: null | undefined | Error | string, state?: ioBroker.State) => void) => void: Callback (error: null | undefined | Error | string, state?: ioBroker.State) => void

getBinaryState(id, callback)

Get a binary state by ID

• id string: State ID, e.g. javascript.0.binary
• callback (error: null | undefined | Error | string, base64?: string) => void) => void: Callback (error: null | undefined | Error | string, base64?: string) => void

setBinaryState(id, _base64, callback)

Set a binary state by ID

• id string: State ID, e.g. javascript.0.binary
• _base64 string: State value as base64 string. Binary states have no acknowledged flag.
• callback (error: null | undefined | Error | string) => void) => void: Callback (error: null | undefined | Error | string) => void

subscribe(pattern, callback)

Subscribe to state changes by pattern. The events will come as 'stateChange' events to the socket.

• pattern string | string[]: Pattern like system.adapter.* or array of states like ['system.adapter.admin.0.memRss', 'system.adapter.admin.0.memHeapTotal']
• callback (error: string | null) => void) => void: Callback (error: string | null) => void

subscribeStates(pattern, callback)

Subscribe to state changes by pattern. Same as subscribe. The events will come as 'stateChange' events to the socket.

• pattern string | string[]: Pattern like system.adapter.* or array of states like ['system.adapter.admin.0.memRss', 'system.adapter.admin.0.memHeapTotal']
• callback (error: string | null) => void) => void: Callback (error: string | null) => void

unsubscribe(pattern, callback)

Unsubscribe from state changes by pattern.

• pattern string | string[]: Pattern like system.adapter.* or array of states like ['system.adapter.admin.0.memRss', 'system.adapter.admin.0.memHeapTotal']
• callback (error: string | null) => void) => void: Callback (error: string | null) => void

unsubscribeStates(pattern, callback)

Unsubscribe from state changes by pattern. Same as unsubscribe. The events will come as 'stateChange' events to the socket.

• pattern string | string[]: Pattern like system.adapter.* or array of states like ['system.adapter.admin.0.memRss', 'system.adapter.admin.0.memHeapTotal']
• callback (error: string | null) => void) => void: Callback (error: string | null) => void

Files

readFile(adapter, fileName, callback)

Read a file from ioBroker DB

• adapter string: instance name, e.g. vis.0
• fileName string: file name, e.g. main/vis-views.json
• callback (error: null | undefined | Error | string, data: Buffer | string, mimeType: string) => void) => void: Callback (error: null | undefined | Error | string, data: Buffer | string, mimeType: string) => void

readFile64(adapter, fileName, callback)

Read a file from ioBroker DB as base64 string

• adapter string: instance name, e.g. vis.0
• fileName string: file name, e.g. main/vis-views.json
• callback (error: null | undefined | Error | string, base64?: string, mimeType?: string) => void) => void: Callback (error: null | undefined | Error | string, base64: string, mimeType: string) => void

writeFile64(adapter, fileName, data64, options, callback?)

Write a file into ioBroker DB as base64 string

• adapter string: instance name, e.g. vis.0
• fileName string: file name, e.g. main/vis-views.json
• data64 string: file content as base64 string
• options {mode?: number} | ((error: null | undefined | Error | string) => void): optional {mode: 0x0644}
• callback? (error: null | undefined | Error | string) => void: Callback (error: null | undefined | Error | string) => void

writeFile(adapter, fileName, data, options?, callback?)

Write a file into ioBroker DB as text This function is overloaded in admin (because admin accepts only base64)

• adapter string: instance name, e.g. vis.0
• fileName string: file name, e.g. main/vis-views.json
• data string: file content as text
• options? {mode?: number} | ((error: null | undefined | Error | string) => void): optional {mode: 0x0644}
• callback? (error: null | undefined | Error | string) => void: Callback (error: null | undefined | Error | string) => void

unlink(adapter, name, callback)

Delete a file in ioBroker DB

• adapter string: instance name, e.g. vis.0
• name string: file name, e.g. main/vis-views.json
• callback (error: null | undefined | Error | string) => void) => void: Callback (error: null | undefined | Error | string) => void

deleteFile(adapter, name, callback)

Delete a file in ioBroker DB (same as "unlink", but only for files)

• adapter string: instance name, e.g. vis.0
• name string: file name, e.g. main/vis-views.json
• callback (error: null | undefined | Error | string) => void) => void: Callback (error: null | undefined | Error | string) => void

deleteFolder(adapter, name, callback)

Delete folder in ioBroker DB (same as unlink, but only for folders)

• adapter string: instance name, e.g. vis.0
• name string: folder name, e.g. main
• callback (error: null | undefined | Error | string) => void) => void: Callback (error: null | undefined | Error | string) => void

renameFile(adapter, oldName, newName, callback)

Rename a file in ioBroker DB

• adapter string: instance name, e.g. vis.0
• oldName string: current file name, e.g. main/vis-views.json
• newName string: new file name, e.g. main/vis-views-new.json
• callback (error: null | undefined | Error | string) => void) => void: Callback (error: null | undefined | Error | string) => void

rename(adapter, oldName, newName, callback)

Rename file or folder in ioBroker DB

• adapter string: instance name, e.g. vis.0
• oldName string: current file name, e.g. main/vis-views.json
• newName string: new file name, e.g. main/vis-views-new.json
• callback (error: null | undefined | Error | string) => void) => void: Callback (error: null | undefined | Error | string) => void

mkdir(adapter, dirName, callback)

Create a folder in ioBroker DB

• adapter string: instance name, e.g. vis.0
• dirName string: desired folder name, e.g. main
• callback (error: null | undefined | Error | string) => void) => void: Callback (error: null | undefined | Error | string) => void

readDir(adapter, dirName, options, callback?)

Read the content of the folder in ioBroker DB

• adapter string: instance name, e.g. vis.0
• dirName string: folder name, e.g. main
• options object | ((error: null | undefined | Error | string, files: ioBroker.ReadDirResult[]) => void): for future use
• callback? (error: null | undefined | Error | string, files: ioBroker.ReadDirResult[]) => void: Callback (error: null | undefined | Error | string, files: Array<{file: string, isDir: boolean, stats: {size: number}, modifiedAt: number, acl: {owner: string, ownerGroup: string, permissions: number, read: boolean, write: boolean}}>) => void

chmodFile(adapter, fileName, options, callback?)

Change a file mode in ioBroker DB

• adapter string: instance name, e.g. vis.0
• fileName string: file name, e.g. main/vis-views.json
• options {mode?: number}: options {mode: 0x644}
• callback? (error: string | Error | null | undefined) => void: Callback (error: string | Error | null | undefined) => void

chownFile(adapter, fileName, options, callback?)

Change file owner in ioBroker DB

• adapter string: instance name, e.g. vis.0
• fileName string: file name, e.g. main/vis-views.json
• options {owner: system.user.${string}; ownerGroup?: system.group.${string}}: options {owner: 'system.user.user', ownerGroup: 'system.group.administrator'} or system.user.user. If ownerGroup is not defined, it will be taken from an owner.
• callback? (error: null | undefined | Error | string) => void: Callback (error: null | undefined | Error | string) => void

fileExists(adapter, fileName, callback)

Check if the file or folder exists in ioBroker DB

• adapter string: instance name, e.g. vis.0
• fileName string: file name, e.g. main/vis-views.json
• callback (error: null | undefined | Error | string, exists?: boolean) => void) => void: Callback (error: null | undefined | Error | string, exists?: boolean) => void

subscribeFiles(id, pattern, callback)

Subscribe to file changes in ioBroker DB

• id string: instance name, e.g. vis.0 or any object ID of type meta. id could have wildcards * too.
• pattern string | string[]: file name pattern, e.g. main/*.json or array of names
• callback (error: null | undefined | Error | string) => void) => void: Callback (error: null | undefined | Error | string) => void

unsubscribeFiles(id, pattern, callback)

Unsubscribe from file changes in ioBroker DB

• id string: instance name, e.g. vis.0 or any object ID of type meta. id could have wildcards * too.
• pattern string | string[]: file name pattern, e.g. main/*.json or array of names
• callback (error: null | undefined | Error | string) => void) => void: Callback (error: null | undefined | Error | string) => void

Admin Methods

List of commands

• authenticate
• updateTokenExpiration
• error
• log
• checkFeatureSupported
• getHistory
• httpGet
• sendTo
• sendToHost
• authEnabled
• logout
• listPermissions
• getUserPermissions
• getVersion
• getAdapterName
• clientSubscribe
• clientUnsubscribe
• getCompactSystemConfig
• getAdapterInstances
• getHostByIp
• requireLog
• readLogs
• cmdExec
• eventsThreshold
• getRatings
• getCurrentInstance
• decrypt
• encrypt
• getIsEasyModeStrict
• getEasyMode
• getAdapters
• updateLicenses
• getCompactInstances
• getCompactAdapters
• getObjectsCount
• getCompactInstalled
• getCompactSystemRepositories
• getCompactRepository
• getCompactHosts
• delState
• getStates
• getForeignStates
• getState
• setState
• getBinaryState
• setBinaryState
• subscribe
• subscribeStates
• unsubscribe
• unsubscribeStates
• addUser
• delUser
• addGroup
• delGroup
• changePassword
• getObject
• getObjects
• getAllObjects
• subscribeObjects
• unsubscribeObjects
• getObjectView
• setObject
• delObject
• extendObject
• getForeignObjects
• delObjects
• readFile
• readFile64
• writeFile64
• writeFile
• unlink
• deleteFile
• deleteFolder
• renameFile
• rename
• mkdir
• readDir
• chmodFile
• chownFile
• fileExists
• subscribeFiles
• unsubscribeFiles

Commands

authenticate(callback)

Wait till the user is authenticated. As the user authenticates himself, the callback will be called

• callback (isUserAuthenticated: boolean, isAuthenticationUsed: boolean) => void) => void: Callback (isUserAuthenticated: boolean, isAuthenticationUsed: boolean) => void

updateTokenExpiration(accessToken, callback)

After the access token is updated, this command must be called to update the session (Only for OAuth2)

• accessToken string: New access token
• callback (error: string | undefined | null, success?: boolean) => void) => void: Callback (error: string | undefined | null, success?: boolean) => void

error(error)

Write error into ioBroker log

• error Error | string: Error object or error text

log(text, level)

Write log entry into ioBroker log

• text string: log text
• level ioBroker.LogLevel: one of ['silly', 'debug', 'info', 'warn', 'error']. The default is 'debug'.

checkFeatureSupported(feature, callback)

Check if the same feature is supported by the current js-controller

• feature SupportedFeature: feature name like CONTROLLER_LICENSE_MANAGER
• callback (error: string | Error | null | undefined, isSupported?: boolean) => void) => void: callback (error: string | Error | null | undefined, isSupported: boolean) => void

getHistory(id, options, callback)

Get the history data from the specific instance

• id string: object ID
• options ioBroker.GetHistoryOptions: History options
• callback (error: string | Error | null | undefined, result: ioBroker.GetHistoryResult) => void) => void: callback (error: string | Error | null | undefined, result: ioBroker.GetHistoryResult) => void

httpGet(url, callback)

Read content of HTTP(s) page server-side (without CORS and stuff)

• url string: Page URL
• callback (error: Error | null | undefined | string, result?: {status: number; statusText: string}, data?: string) => void: callback (error: Error | null, result?: { status: number; statusText: string }, data?: string) => void

sendTo(adapterInstance, command, message, callback)

Send the message to specific instance

• adapterInstance string: instance name, e.g. history.0
• command string: command name
• message any: the message is instance-dependent
• callback (result: any) => void) => void: callback (result: any) => void

sendToHost(host, command, message, callback)

Send a message to the specific host. Host can answer to the following commands: cmdExec, getRepository, getInstalled, getInstalledAdapter, getVersion, getDiagData, getLocationOnDisk, getDevList, getLogs, getHostInfo, delLogs, readDirAsZip, writeDirAsZip, readObjectsAsZip, writeObjectsAsZip, checkLogging, updateMultihost.

• host string: Host name. With or without 'system.host.' prefix
• command * 'shell' | 'cmdExec' | 'getRepository' | 'getInstalled' | 'getInstalledAdapter' | 'getVersion' | 'getDiagData' | 'getLocationOnDisk' | 'getDevList' | 'getLogs' | 'getLogFile' | 'getLogFiles' | 'getHostInfo' | 'getHostInfoShort' | 'delLogs' | 'readDirAsZip' | 'writeDirAsZip' | 'readObjectsAsZip' | 'writeObjectsAsZip' | 'checkLogging' | 'updateMultihost' | 'upgradeController' | 'upgradeAdapterWithWebserver' | 'getInterfaces' | 'upload' | 'rebuildAdapter' | 'readBaseSettings' | 'writeBaseSettings' | 'addNotification' | 'clearNotifications' | 'getNotifications' | 'updateLicenses' | 'upgradeOsPackages' | 'restartController' | 'sendToSentry'*: Host command
• message any: the message is command-specific
• callback (result: {error?: string; result?: any}) => void) => void: callback (result: { error?: string; result?: any }) => void

authEnabled(callback)

Ask server is authentication enabled, and if the user authenticated

• callback (isUserAuthenticated: boolean | Error | string, isAuthenticationUsed: boolean) => void) => void: callback (isUserAuthenticated: boolean | Error | string, isAuthenticationUsed: boolean) => void

logout(callback)

Logout user

• callback ioBroker.ErrorCallback: callback (error?: Error) => void

listPermissions(callback)

List commands and permissions

• callback (permissions: Record< string, {type: 'object' | 'state' | 'users' | 'other' | 'file' | ''; operation: SocketOperation} >) => void: callback (permissions: Record<string, { type: 'object' | 'state' | 'users' | 'other' | 'file' | ''; operation: SocketOperation }>) => void

getUserPermissions(callback)

Get user permissions

• callback (error: string | null | undefined, userPermissions?: SocketACL | null) => void) => void: callback (error: string | null | undefined, userPermissions?: SocketACL | null) => void

getVersion(callback)

Get the adapter version. Not the socket-classes version!

• callback (error: string | Error | null | undefined, version: string | undefined, adapterName: string) => void: callback (error: string | Error | null | undefined, version: string | undefined, adapterName: string) => void

getAdapterName(callback)

Get adapter name: "iobroker.ws", "iobroker.socketio", "iobroker.web", "iobroker.admin"

• callback (error: string | Error | null | undefined, adapterName: string) => void) => void: callback (error: string | Error | null | undefined, version: string | undefined, adapterName: string) => void

clientSubscribe(targetInstance, messageType, data, callback)

Client subscribes to specific instance's messages. Client informs a specific instance about subscription on its messages. After subscription, the socket will receive "im" messages from the desired instance The target instance MUST acknowledge the subscription and return result

• targetInstance string: Instance name, e.g., 'cameras.0'
• messageType string: Message type, e.g., 'startRecording/cam1'
• data any: Optional data object, e.g., {width: 640, height: 480}
• callback (error: string | null | Error | undefined, result?: {accepted: boolean; heartbeat?: number; error?: string}) => void: Callback (error: string | null, result?:{ accepted: boolean; heartbeat?: number; error?: string; }) => void

clientUnsubscribe(targetInstance, messageType, callback)

Client unsubscribes from specific instance's messages. The target instance MUST NOT acknowledge the un-subscription

• targetInstance string: Instance name, e.g., 'cameras.0'
• messageType string: Message type, e.g., 'startRecording/cam1'
• callback (error: string | null | Error | undefined) => void) => void: Callback (error: string | null) => void

getCompactSystemConfig(callback)

Get the system configuration in a compact form to save bandwidth.

• callback (error: string | null | Error | undefined, systemConfig?: {common: ioBroker.SystemConfigCommon; native?: {secret: string; vendor?: any}}) => void: - Callback function (error: string | null, systemConfig?: { common: any; native?: { secret: string } }) => void

getAdapterInstances(adapterName, callback)

Read all instances of the given adapter, or all instances of all adapters if adapterName is not defined

• adapterName string | undefined: adapter name, e.g. history. To get all instances of all adapters, just place here "".
• callback (error: null | undefined | Error | string, instanceList?: ioBroker.InstanceObject[]) => void) => void: callback (error: null | undefined | Error | string, instanceList?: ioBroker.InstanceObject[]) => void

Admin

getHostByIp(ip, callback?)

Read the host object by IP address.

• ip string: - IP address, e.g., 192.168.1.1. IPv4 or IPv6
• callback? (error: string | null | Error | undefined, hostObject?: ioBroker.HostObject | null) => void: - Callback function (ip: string, obj: ioBroker.HostObject | null) => void

requireLog(isEnabled, callback?)

Activate or deactivate logging events. Events will be sent to the socket as log events. Adapter must have common.logTransporter = true.

• isEnabled boolean: - Is logging enabled
• callback? (error: string | null | Error | undefined) => void: - Callback function (error: string | null) => void

readLogs(host, callback?)

Get the log files from the given host.

• host string: - Host ID, e.g., system.host.raspberrypi
• callback? (error: string | null | Error | undefined, list?: {fileName: string; size: number}[]) => void: - Callback function (error: string | null, list?: { fileName: string; size: number }[]) => void

cmdExec(host, id, cmd, files?, callback?)

Execute the shell command on host/controller. The following response commands are expected: cmdStdout, cmdStderr, cmdExit.

• host string: - Host name, e.g., system.host.raspberrypi
• id number: - Session ID, e.g., Date.now(). This session ID will come in events cmdStdout, cmdStderr, cmdExit
• cmd string: - Command to execute
• files? CommandFile[] | ((error: string | null | Error | undefined) => void): - Optional files to send with the command (base64 encoded). The command can refer to them just by name. Requires controller feature CONTROLLER_CMD_EXEC_FILES.
• callback? (error: string | null | Error | undefined) => void: - Callback function (error: string | null) => void

eventsThreshold(isActive)

Enable or disable the event threshold. Used only for admin to limit the number of events to the front-end.

• isActive boolean: - If true, then events will be limited

getRatings(update, callback?)

Get the ratings of adapters.

• update boolean | ((error: string | null | Error | undefined, ratings?: Ratings) => void): - If true, the ratings will be read from the central server, if false from the local cache
• callback? (error: string | null | Error | undefined, ratings?: Ratings) => void: - Callback function (error: string | null, ratings?: Ratings) => void

getCurrentInstance(callback)

Get the current instance name, like "admin.0"

• callback (error: string | null | Error | undefined, namespace: string) => void) => void: - Callback function (error: string | null, namespace?: string) => void

decrypt(encryptedText, callback)

Decrypts text with the system secret key.

• encryptedText string: - Encrypted text
• callback (error: string | null | Error | undefined, decryptedText?: string) => void) => void: - Callback function (error: string | null, decryptedText?: string) => void

encrypt(plainText, callback)

Encrypts text with the system secret key.

• plainText string: - Plain text to encrypt
• callback (error: string | null | Error | undefined, encryptedText?: string) => void) => void: - Callback function (error: string | null, encryptedText?: string) => void

getIsEasyModeStrict(callback)

Get if the admin has easy mode enabled.

• callback (error: string | null | Error | undefined, isEasyModeStrict?: boolean) => void) => void: - Callback function (error: string | null, isEasyModeStrict?: boolean) => void

getEasyMode(callback)

Get easy mode configuration.

• callback (error: string | null | Error | undefined, easyModeConfig?: {strict: boolean; configs: InstanceConfig[]}) => void: - Callback function (error: string | null, easyModeConfig?: { strict: boolean; configs: InstanceConfig[] }) => void

getAdapters(adapterName, callback)

Get all adapter as objects.

• adapterName string: - Optional adapter name
• callback (error: string | null | Error | undefined, result?: ioBroker.AdapterObject[]) => void) => void: - Callback function (error: string | null, results?: ioBroker.Object[]) => void

updateLicenses(login, password, callback)

Read software licenses (vis, knx, ...) from ioBroker.net cloud for given user

• login string: - Cloud login
• password string: - Cloud password
• callback (error: string | null | Error | undefined, result?: License[]) => void) => void: - Callback function (error: string | null, results?: License[]) => void

getCompactInstances(callback)

Get all instances in a compact form to save bandwidth.

• callback (error: string | null | Error | undefined, result?: Record<string, CompactInstanceInfo>) => void) => void: - Callback function (error: string | null, results?: Record<string, { adminTab: boolean; name: string; icon: string; enabled: boolean }>) => void

getCompactAdapters(callback)

Get all adapters in a compact form to save bandwidth.

• callback (error: string | null | Error | undefined, result?: Record<string, CompactAdapterInfo>) => void) => void: - Callback function (error: string | null, results?: Record<string, { icon: string; v: string; iv: string }>) => void

getObjectsCount(callback)

Count the objects and the objects of every type. Reading all objects only to count them transfers the whole database - tens of megabytes on a grown installation, and it blocks this process while it packs them up. This counts them where they are and answers with numbers. Announced as the feature OBJECTS_COUNT.

• callback (error: string | null | Error | undefined, result?: ObjectsCount) => void) => void: - Callback function (error: string | null, result?: ObjectsCount) => void

getCompactInstalled(host, callback)

Get all installed adapters in a compact form to save bandwidth.

• host string: - Host name, e.g., system.host.raspberrypi
• callback (result?: Record<string, {version: string}>) => void) => void: - Callback function (error: string | null, results?: Record<string, { version: string }>) => void

getCompactSystemRepositories(callback)

Get system repositories in a compact form to save bandwidth.

• callback (error: string | null | Error | undefined, systemRepositories?: CompactSystemRepository) => void) => void: - Callback function (error: string | null, systemRepositories?: { common: any; native?: { repositories: Record<string, { json: { _repoInfo: any } } } }) => void

getCompactRepository(host, callback)

Get the repository in a compact form to save bandwidth. Answered from the objects admin holds in memory where possible. Asking the host means several megabytes of repository through the message box for two fields per adapter, which made every start of the GUI wait seconds for it.

• host string: - Host name, e.g., system.host.raspberrypi
• callback (result: Record<string, {version: string; icon?: string}>) => void) => void: - Callback function (error: string | null, results?: Record<string, { version: string; icon?: string }>) => void

getCompactHosts(callback)

Get all hosts in a compact form to save bandwidth.

• callback (error: string | null | Error | undefined, hosts?: CompactHost[]) => void) => void: - Callback function (error: string | null, results?: Record<string, { common: { name: string; icon: string; color: string; installedVersion: string }; native: { hardware: { networkInterfaces: any[] } } }>) => void

States

delState(id, callback?)

Delete a state. The corresponding object will be deleted too.

• id string: - State ID
• callback? (error: string | null | Error | undefined) => void: - Callback function (error: string | null) => void

getStates(pattern, callback)

Get states by pattern of current adapter

• pattern string | string[] | undefined: optional pattern, like system.adapter.* or array of state IDs. If the pattern is omitted, you will get ALL states of current adapter
• callback (error: null | undefined | Error | string, states?: Record<string, ioBroker.State>) => void) => void: callback (error: null | undefined | Error | string, states?: Record<string, ioBroker.State>) => void

getForeignStates(pattern, callback)

Same as getStates

• pattern string | string[]: pattern like system.adapter.* or array of state IDs
• callback (error: null | undefined | Error | string, states?: Record<string, ioBroker.State>) => void) => void: callback (error: null | undefined | Error | string, states?: Record<string, ioBroker.State>) => void

getState(id, callback)

Get a state by ID

• id string: State ID, e.g. system.adapter.admin.0.memRss
• callback (error: null | undefined | Error | string, state?: ioBroker.State) => void) => void: Callback (error: null | undefined | Error | string, state?: ioBroker.State) => void

setState(id, state, callback)

Set a state by ID

• id string: State ID, e.g. system.adapter.admin.0.memRss
• state ioBroker.SettableState: State value or object, e.g. {val: 123, ack: true}
• callback (error: null | undefined | Error | string, state?: ioBroker.State) => void) => void: Callback (error: null | undefined | Error | string, state?: ioBroker.State) => void

getBinaryState(id, callback)

Get a binary state by ID

• id string: State ID, e.g. javascript.0.binary
• callback (error: null | undefined | Error | string, base64?: string) => void) => void: Callback (error: null | undefined | Error | string, base64?: string) => void

setBinaryState(id, _base64, callback)

Set a binary state by ID

• id string: State ID, e.g. javascript.0.binary
• _base64 string: State value as base64 string. Binary states have no acknowledged flag.
• callback (error: null | undefined | Error | string) => void) => void: Callback (error: null | undefined | Error | string) => void

subscribe(pattern, callback)

Subscribe to state changes by pattern. The events will come as 'stateChange' events to the socket.

• pattern string | string[]: Pattern like system.adapter.* or array of states like ['system.adapter.admin.0.memRss', 'system.adapter.admin.0.memHeapTotal']
• callback (error: string | null) => void) => void: Callback (error: string | null) => void

subscribeStates(pattern, callback)

Subscribe to state changes by pattern. Same as subscribe. The events will come as 'stateChange' events to the socket.

• pattern string | string[]: Pattern like system.adapter.* or array of states like ['system.adapter.admin.0.memRss', 'system.adapter.admin.0.memHeapTotal']
• callback (error: string | null) => void) => void: Callback (error: string | null) => void

unsubscribe(pattern, callback)

Unsubscribe from state changes by pattern.

• pattern string | string[]: Pattern like system.adapter.* or array of states like ['system.adapter.admin.0.memRss', 'system.adapter.admin.0.memHeapTotal']
• callback (error: string | null) => void) => void: Callback (error: string | null) => void

unsubscribeStates(pattern, callback)

Unsubscribe from state changes by pattern. Same as unsubscribe. The events will come as 'stateChange' events to the socket.

• pattern string | string[]: Pattern like system.adapter.* or array of states like ['system.adapter.admin.0.memRss', 'system.adapter.admin.0.memHeapTotal']
• callback (error: string | null) => void) => void: Callback (error: string | null) => void

Users

addUser(user, pass, callback?)

Add a new user.

• user string: - User name, e.g., benjamin
• pass string: - User password
• callback? (error: string | null | Error | undefined) => void: - Callback function (error: string | null) => void

delUser(user, callback?)

Delete an existing user. Admin cannot be deleted.

• user string: - User name, e.g., benjamin
• callback? (error: string | null | Error | undefined) => void: - Callback function (error: string | null) => void

addGroup(group, desc, acl, callback?)

Add a new group.

• group string: - Group name, e.g., users
• desc ioBroker.StringOrTranslated | null: - Optional description
• acl Omit<ioBroker.PermissionSet, 'user' | 'groups'> | null: - Optional access control list object, e.g., {"object":{"list":true,"read":true,"write":false,"delete":false},"state":{"list":true,"read":true,"write":true,"create":true,"delete":false},"users":{"list":true,"read":true,"write":false,"create":false,"delete":false},"other":{"execute":false,"http":true,"sendto":false},"file":{"list":true,"read":true,"write":false,"create":false,"delete":false}}
• callback? (error: string | null | Error | undefined) => void: - Callback function (error: string | null) => void

delGroup(group, callback?)

Delete an existing group. Administrator group cannot be deleted.

• group string: - Group name, e.g., users
• callback? (error: string | null | Error | undefined) => void: - Callback function (error: string | null) => void

changePassword(user, pass, callback?)

Change user password.

• user string: - User name, e.g., benjamin
• pass string: - New password
• callback? (error: string | null | Error | undefined) => void: - Callback function (error: string | null) => void

Objects

getObject(id, callback)

Get one object.

• id string: Object ID
• callback (error: Error | undefined | string | null, obj?: ioBroker.Object) => void) => void: Callback (error: string | null, obj?: ioBroker.Object) => void

getObjects(list, callback)

Get all objects that are relevant for the web: all states and enums with rooms. This is a non-admin version of "all objects" and will be overloaded in admin

• list string[] | null: Optional list of IDs
• callback (error: Error | undefined | string | null, objs?: Record<string, ioBroker.Object>) => void) => void: Callback (error: string | null, objs?: Record<string, ioBroker.Object>) => void

getAllObjects(callback)

Get all objects that are relevant for the web: all states and enums with rooms.

• callback (error: null | undefined | Error | string, result?: Record<string, ioBroker.Object>) => void) => void: - Callback function (error: string | null, objects?: Record<string, ioBroker.Object>) => void

subscribeObjects(pattern, callback)

Subscribe to object changes by pattern. The events will come as 'objectChange' events to the socket.

• pattern string | string[]: Pattern like system.adapter.* or array of IDs like ['system.adapter.admin.0.memRss', 'system.adapter.admin.0.memHeapTotal']
• callback (error: Error | undefined | string | null) => void) => void: Callback (error: string | null) => void

unsubscribeObjects(pattern, callback)

Unsubscribe from object changes by pattern.

• pattern string | string[]: Pattern like system.adapter.* or array of IDs like ['system.adapter.admin.0.memRss', 'system.adapter.admin.0.memHeapTotal']
• callback (error: string | null | Error | undefined) => void) => void: Callback (error: string | null) => void

getObjectView(design, search, params, callback)

Get a view of objects. Make a query to the object database.

• design string: Design name, e.g., 'system' or other designs like custom, but it must exist object _design/custom. To 99,9% use system.
• search string: Search name, object type, like state, instance, adapter, host, ...
• params {startkey?: string; endkey?: string; depth?: number}: Parameters for the query, e.g., {startkey: 'system.adapter.', endkey: 'system.adapter.\u9999', depth?: number}
• callback (error: string | null | Error | undefined, result?: {rows: {id: string; value: ioBroker.Object & {virtual: boolean; hasChildren: number;};}[];}) => void: Callback (error: string | null, result?: { rows: Array<GetObjectViewItem> }) => void

setObject(id, obj, callback)

Set an object.

• id string: Object ID
• obj ioBroker.Object: Object to set
• callback (error: string | null | Error | undefined) => void) => void: Callback (error: string | null) => void

delObject(id, _options, callback)

Delete an object. Only deletion of flot and fullcalendar objects is allowed

• id string: Object ID, like 'flot.0.myChart'
• _options any: Options for deletion. Ignored
• callback (error: string | null | Error | undefined) => void) => void: Callback (error: string | null) => void

extendObject(id, obj, callback?)

Extend the existing object.

• id string: - Object ID
• obj Partial<ioBroker.Object>: - New parts of the object, e.g., {common: {name: 'new name'}}
• callback? (error: string | null | Error | undefined) => void: - Callback function (error: string | null) => void

getForeignObjects(pattern, type, callback?)

Read objects by pattern.

• pattern string: - Pattern like system.adapter.admin.0.*
• type * ioBroker.ObjectType | undefined | ((error: string | null | Error | undefined, objects?: Record<string, ioBroker.Object>) => void)*: - Type of objects to delete, like state, channel, device, host, adapter. Default - state
• callback? (error: string | null | Error | undefined, objects?: Record<string, ioBroker.Object>) => void: - Callback function (error: string | null, objects?: Record<string, ioBroker.Object>) => void

delObjects(id, options?, callback?)

Delete an object or objects recursively. Objects with dontDelete cannot be deleted. Same as delObject but with recursive: true.

• id string: - Object ID, like 'adapterName.0.channel'
• options? ioBroker.DelObjectOptions | ((error: string | null | Error | undefined) => void) | null: - Options for deletion.
• callback? (error: string | null | Error | undefined) => void: - Callback function (error: string | null) => void

Files

readFile(adapter, fileName, callback)

Read a file from ioBroker DB

• adapter string: instance name, e.g. vis.0
• fileName string: file name, e.g. main/vis-views.json
• callback (error: null | undefined | Error | string, data: Buffer | string, mimeType: string) => void) => void: Callback (error: null | undefined | Error | string, data: Buffer | string, mimeType: string) => void

readFile64(adapter, fileName, callback)

Read a file from ioBroker DB as base64 string

• adapter string: instance name, e.g. vis.0
• fileName string: file name, e.g. main/vis-views.json
• callback (error: null | undefined | Error | string, base64?: string, mimeType?: string) => void) => void: Callback (error: null | undefined | Error | string, base64: string, mimeType: string) => void

writeFile64(adapter, fileName, data64, options, callback?)

Write a file into ioBroker DB as base64 string

• adapter string: instance name, e.g. vis.0
• fileName string: file name, e.g. main/vis-views.json
• data64 string: file content as base64 string
• options {mode?: number} | ((error: null | undefined | Error | string) => void): optional {mode: 0x0644}
• callback? (error: null | undefined | Error | string) => void: Callback (error: null | undefined | Error | string) => void

writeFile(adapter, fileName, data, options?, callback?)

Write a file into ioBroker DB as text This function is overloaded in admin (because admin accepts only base64)

• adapter string: instance name, e.g. vis.0
• fileName string: file name, e.g. main/vis-views.json
• data string: file content as text
• options? {mode?: number} | ((error: null | undefined | Error | string) => void): optional {mode: 0x0644}
• callback? (error: null | undefined | Error | string) => void: Callback (error: null | undefined | Error | string) => void

unlink(adapter, name, callback)

Delete a file in ioBroker DB

• adapter string: instance name, e.g. vis.0
• name string: file name, e.g. main/vis-views.json
• callback (error: null | undefined | Error | string) => void) => void: Callback (error: null | undefined | Error | string) => void

deleteFile(adapter, name, callback)

Delete a file in ioBroker DB (same as "unlink", but only for files)

• adapter string: instance name, e.g. vis.0
• name string: file name, e.g. main/vis-views.json
• callback (error: null | undefined | Error | string) => void) => void: Callback (error: null | undefined | Error | string) => void

deleteFolder(adapter, name, callback)

Delete folder in ioBroker DB (same as unlink, but only for folders)

• adapter string: instance name, e.g. vis.0
• name string: folder name, e.g. main
• callback (error: null | undefined | Error | string) => void) => void: Callback (error: null | undefined | Error | string) => void

renameFile(adapter, oldName, newName, callback)

Rename a file in ioBroker DB

• adapter string: instance name, e.g. vis.0
• oldName string: current file name, e.g. main/vis-views.json
• newName string: new file name, e.g. main/vis-views-new.json
• callback (error: null | undefined | Error | string) => void) => void: Callback (error: null | undefined | Error | string) => void

rename(adapter, oldName, newName, callback)

Rename file or folder in ioBroker DB

• adapter string: instance name, e.g. vis.0
• oldName string: current file name, e.g. main/vis-views.json
• newName string: new file name, e.g. main/vis-views-new.json
• callback (error: null | undefined | Error | string) => void) => void: Callback (error: null | undefined | Error | string) => void

mkdir(adapter, dirName, callback)

Create a folder in ioBroker DB

• adapter string: instance name, e.g. vis.0
• dirName string: desired folder name, e.g. main
• callback (error: null | undefined | Error | string) => void) => void: Callback (error: null | undefined | Error | string) => void

readDir(adapter, dirName, options, callback?)

Read the content of the folder in ioBroker DB

• adapter string: instance name, e.g. vis.0
• dirName string: folder name, e.g. main
• options object | ((error: null | undefined | Error | string, files: ioBroker.ReadDirResult[]) => void): for future use
• callback? (error: null | undefined | Error | string, files: ioBroker.ReadDirResult[]) => void: Callback (error: null | undefined | Error | string, files: Array<{file: string, isDir: boolean, stats: {size: number}, modifiedAt: number, acl: {owner: string, ownerGroup: string, permissions: number, read: boolean, write: boolean}}>) => void

chmodFile(adapter, fileName, options, callback?)

Change a file mode in ioBroker DB

• adapter string: instance name, e.g. vis.0
• fileName string: file name, e.g. main/vis-views.json
• options {mode?: number}: options {mode: 0x644}
• callback? (error: string | Error | null | undefined) => void: Callback (error: string | Error | null | undefined) => void

chownFile(adapter, fileName, options, callback?)

Change file owner in ioBroker DB

• adapter string: instance name, e.g. vis.0
• fileName string: file name, e.g. main/vis-views.json
• options {owner: system.user.${string}; ownerGroup?: system.group.${string}}: options {owner: 'system.user.user', ownerGroup: 'system.group.administrator'} or system.user.user. If ownerGroup is not defined, it will be taken from an owner.
• callback? (error: null | undefined | Error | string) => void: Callback (error: null | undefined | Error | string) => void

fileExists(adapter, fileName, callback)

Check if the file or folder exists in ioBroker DB

• adapter string: instance name, e.g. vis.0
• fileName string: file name, e.g. main/vis-views.json
• callback (error: null | undefined | Error | string, exists?: boolean) => void) => void: Callback (error: null | undefined | Error | string, exists?: boolean) => void

subscribeFiles(id, pattern, callback)

Subscribe to file changes in ioBroker DB

• id string: instance name, e.g. vis.0 or any object ID of type meta. id could have wildcards * too.
• pattern string | string[]: file name pattern, e.g. main/*.json or array of names
• callback (error: null | undefined | Error | string) => void) => void: Callback (error: null | undefined | Error | string) => void

unsubscribeFiles(id, pattern, callback)

Unsubscribe from file changes in ioBroker DB

• id string: instance name, e.g. vis.0 or any object ID of type meta. id could have wildcards * too.
• pattern string | string[]: file name pattern, e.g. main/*.json or array of names
• callback (error: null | undefined | Error | string) => void) => void: Callback (error: null | undefined | Error | string) => void

2.7.1 (2026-10-07)

• (@GermanBluefox) Added: an event only reaches a connection whose user may read what it is about. A subscription says which ids a client is interested in, never which ids it may see - subscribe asks whether the user may read states at all, so whoever subscribed to * was told about every state of the system, the ACL of the single objects notwithstanding, and the same went for objects and for files. The fan-out asks that question now, for state, object and file events alike. Members of the administrator group are not restricted, as everywhere else, and with authentication switched off every connection is the configured default user - so for most installations nothing changes at all. Where restricted users exist, they will see less than before: that is the point, but it is the kind of change that comes back as "my user stopped getting updates". The database decides, not this package: mayRead of js-controller 8.0 and newer is asked where it exists, which knows the ACL of a state rather than that of its object and the mode of a single file rather than that of the adapter; an older controller is asked for the object instead, which is coarser but refuses in the same direction. One question per user and thing, remembered until the object - or the rights themselves - change, and the objects are watched from the first decision on, so an installation whose connections are all administrators never asks anything
• (@GermanBluefox) Changed: publish and publishFile answer true where the event is on its way to the client, which now includes the moment it waits for the decision described above; false means the client is not subscribed to it, or may not see it. Only the first event of a thing ever waits, and only the newest one of it, so nothing can overtake it

2.7.0 (2026-10-05)

• (@GermanBluefox) Added: every command that sends a message now names the user of the connection - sendTo, sendToHost, cmdExec, clientSubscribe, clientUnsubscribe and the "nobody subscribed" notice. Objects, states and files have always been read and written with { user } so the database applies the ACLs of the logged-in user; a message had no such channel, so the receiving instance saw from and nothing else and had to act with its own rights - a GUI user who may use sendTo could have an adapter do things their own ACL forbids. It travels as a send option, which js-controller 7.2.5 and newer pass on to the message as obj.user; an older one ignores it, so nothing breaks, and a receiving adapter treats the field as optional

2.6.2 (2026-10-02)

• (@GermanBluefox) Fixed: a websocket whose access token was not accepted stayed open without a single command handler. The client was asked to re-authenticate, fetched a new token within milliseconds and announced it with updateTokenExpiration - the one command that is exempt from the session check exactly for this - but nobody was listening. The client waited for an answer that could not come until its own three second timeout closed the connection, burnt its single-use refresh token for nothing and had to start over, which is why the GUI took seconds to come up with authentication enabled and sometimes did not come up at all. The handlers are installed now, with an empty ACL: every command that needs a permission is still refused, only the announcement of a token gets through
• (@GermanBluefox) Fixed: an announced access token now finishes the authentication of such a socket instead of only moving its expiration date. The connection carries on with the user of the token, so no reconnect and no second refresh is needed
• (@GermanBluefox) Fixed: authenticate of a socket that is waiting for a token is answered when the token arrives, instead of being answered with "authenticated" although the socket has no user
• (@GermanBluefox) Fixed: reauthenticate was sent twice for the same connection, so a client started two token refreshes and used up two refresh tokens
• (@GermanBluefox) Changed: that a socket is not authenticated is logged at debug instead of silly, so the case is visible without raising the level of the whole adapter

2.6.1 (2026-10-01)

• (@GermanBluefox) getCompactRepository is answered from the objects admin holds in memory instead of asking the host. The host answers getRepository with the whole merged repository - several megabytes through the message box for the two fields per adapter that the GUI uses - and every start of the admin GUI waited seconds for it (measured on a fast machine with three active repositories: 3140 ms, now 38 ms, with a byte-identical answer). A host without an object cache, or an active repository that was never downloaded, still goes through the host
• (@GermanBluefox) The host is still asked for the repository, but ten seconds later and at most once an hour, and nobody waits for the answer: the statistics, the check for a new Docker image and for OS updates, the blocklist and the automatic adapter upgrade hang on that command and nothing else triggers them
• (@GermanBluefox) A controller that announces CONTROLLER_REPOSITORY_COMPACT is asked getRepositoryCompact, so the message box no longer carries the whole repository when the host has to be asked after all

2.6.0 (2026-09-29)

• (@GermanBluefox) Added #countObjects() method to count the objects and the objects of every type. Reading all objects only to count them transfers the whole database - tens of megabytes on a grown installation, and it blocks this process while it packs them up. This counts them where they are and answers with numbers. Announced as the feature OBJECTS_COUNT.

2.5.0 (2026-09-23)

• (@GermanBluefox) Security: the files inside a folder are deleted and renamed with the user of the socket, so js-controller checks the permissions for every file and not only for the folder
• (@GermanBluefox) logout does not crash on a ws socket that has no _query (cookie authentication or legacy session)
• (@GermanBluefox) The objectChange event of a deleted system.config does not crash publish()
• (@GermanBluefox) A socket with subscriptions can be re-subscribed on a fresh commands instance without a TypeError
• (@GermanBluefox) writeFile, delObject and delObjects answer a permission error via the callback also when the options are omitted
• (@GermanBluefox) Wildcard entries of the IP white list like 192.168.1.* are matched
• (@GermanBluefox) The event threshold is not disabled by a check that runs while it is being activated
• (@GermanBluefox) Instances are informed about a disconnected socket even if the socket has never subscribed to states, objects, files or logs
• (@GermanBluefox) getAdapters(adapterName) delivers the requested adapter instead of an empty list
• (@GermanBluefox) updateRatings() sends the uuid of the system when no uuid is given
• (@GermanBluefox) getObjectView with depth returns the root object also for a start key without a trailing dot
• (@GermanBluefox) readLogs recognizes absolute Windows paths like C:\iobroker\log
• (@GermanBluefox) Added detailed unit tests for all classes
• (@GermanBluefox) Migrated tasks.js to TypeScript (tasks.ts)

2.4.4 (2026-09-03)

• (@GermanBluefox) A socket keeps working for one minute after its access token has expired and is asked to refresh the token (reauthenticate) instead of being cut off at once. The refresh timer of a browser tab in the background fires late, so the connection was lost although the user had a valid refresh token
• (@GermanBluefox) updateTokenExpiration is accepted for a socket with an expired session, as it is the only way to make the session valid again. The new token must belong to the same user as the socket
• (@GermanBluefox) Removed the dead re-read of the access token before its expiration (the condition was inverted and a token is never prolonged in place)

2.4.3 (2026-08-31)

• (@GermanBluefox) Log messages are only sent to the sockets that subscribed to them. sendLog() emitted log to every connected socket, so as soon as one client called requireLog(true), all other clients received the log too - including clients of other browsers and clients whose user does not have the rights to subscribe to the log at all.
• (@GermanBluefox) logout destroys the express session again. It used socket.id as the session id, which only worked as long as @iobroker/ws-server filled the socket id with the session id from the connect.sid cookie. The socket id is a per-connection transport identifier generated on the server now, so the session to destroy is taken from socket._sessionID / socket.conn.request.sessionID instead.
• (@joltcoke) Decode the websocket auth query so encoded credentials work

2.4.0 (2026-08-27)

• (@joltcoke) Security: an upgrade request that carries neither credentials nor a cookie header no longer crashes the adapter. sessionID is assigned only inside the cookie branch of authorize(), so such a request reached the session store lookup with it still undefined and js-controller threw while validating the id. The exception escaped the synchronous verifyClient() callback of the websocket server, so any unauthenticated client could stop an instance running with auth: true. The request is now rejected through auth.fail(), and PassportHttpRequest.sessionID is declared optional so the compiler rejects a future unguarded use. Affects 2.2.21 up to and including 2.3.8. Reported and fixed by Florian Schirmer.
• (@GermanBluefox) Security: authorize() answers every upgrade request exactly once now and turns an unexpected exception into a regular rejection instead of letting it escape into the upgrade handler, so a future error on that path cannot take the adapter down again.

2.3.8 (2026-08-24)

• (@GermanBluefox) Security: decrypt and encrypt only serve a request from the process-wide cached system secret if the caller is an administrator. The cache is shared across all sockets, so once any user who may read system.config had populated it, every authenticated user could encrypt and decrypt with the system secret regardless of their own rights. For non-administrators the secret is now resolved through a read that is ACL-checked for the calling user.
• (@GermanBluefox) Security: clientSubscribe and clientUnsubscribe now require the other.sendto permission. They deliver a message to an arbitrary adapter instance via sendTo, but were not covered by any permission check, so an authenticated user without other.sendto could reach any instance. Reported by Santosh Kumar Puppala.
• (@GermanBluefox) Security: eventsThreshold now requires the other.execute permission. Enabling the threshold unsubscribes the adapter from all state patterns for every connected client, so it must not be reachable by a low-privilege user.

2.3.6 (2026-06-20)

• (@GermanBluefox) Updated packages
• (@GermanBluefox) Corrected type

2.3.4 (2026-06-08)

• (@GermanBluefox) Extended cmdExec with files
• (@GermanBluefox) Migrated to TS 6

2.3.2 (2026-04-17)

• (@GermanBluefox) Implement getAllObjects in common commands. Made it available in web and admin. But they are different in admin and web

2.3.1 (2026-04-12)

• (@GermanBluefox) Moved getCompactSystemConfig to common commands. Made it available in web and admin.
• (@Marc-Berg) Emit tokenInfo event with exp on socket connection

2.2.21 (2026-01-25)

• (@Copilot) Added a missing return statement for Bearer token auth

2.2.20 (2025-07-22)

• (@GermanBluefox) Fixed change of the language in the admin

2.2.19 (2025-06-21)

• (@GermanBluefox) Added an option to disable filling of info.connected

2.2.18 (2025-04-29)

• (@GermanBluefox) Send reauthenticate command if token expired

2.2.16 (2025-04-27)

• (@GermanBluefox) Typing improvement

2.2.12 (2025-04-16)

• (@GermanBluefox) Make secret optional for cloud usage

2.2.11 (2025-04-15)

• (@GermanBluefox) Make objects optional for SocketAdmin

2.2.9 (2025-04-15)

• (@GermanBluefox) Removed debug text

2.2.8 (2025-04-11)

• (@GermanBluefox) Deliver vendor information in getCompactSystemConfig command

2.2.7 (2025-04-01)

• (@GermanBluefox) Changed the order of authentications. Basic authentication will be checked as the last one.
• (@GermanBluefox) Added the setting to disable basic authentication

2.2.2 (2025-03-29)

• (@GermanBluefox) Corrected functionality as a client

2.2.1 (2025-03-25)

• (@GermanBluefox) Allowed the authentication by token in the query

2.2.0 (2025-03-04)

• (@GermanBluefox) Removed debug text
• (@GermanBluefox) Moved to TypeScript 5.8

2.1.17 (2025-03-03)

• (@GermanBluefox) Corrected the user's right check

2.1.16 (2025-02-28)

• (@GermanBluefox) Added logout with bearer token

2.1.12 (2025-02-26)

• (@GermanBluefox) Added login with a token in the query or as bearer token

2.1.7 (2025-02-23)

• (@GermanBluefox) Added support for OAuth2 authentication

2.0.12 (2025-02-11)

• (@GermanBluefox) Corrected language settings

2.0.11 (2025-02-11)

• (@GermanBluefox) Code migrated to TypeScript

1.6.2 (2024-12-01)

• (@GermanBluefox) Caught the error if no authentication and logout called

1.6.1 (2024-10-05)

• (@GermanBluefox) Added support for iobroker.SocketIO with TypeScript

1.5.6 (2024-06-26)

• (@GermanBluefox) Corrected call of getObjectView with null parameter

1.5.5 (2024-06-26)

• (@GermanBluefox) updated packages

1.5.4 (2024-06-02)

• (@GermanBluefox) extend getCompactInstancesmethod with version information

1.5.2 (2024-05-28)

• (foxriver76) ensure compatible adapter-core version

1.5.0 (2024-02-22)

• (@GermanBluefox) Extended getObjects function with the possibility to read the list of IDs in admin

1.4.6 (2023-10-19)

• (@GermanBluefox) Added publishInstanceMessageAll command

1.4.4 (2023-10-11)

• (@GermanBluefox) Caught errors by subscribe/unsubscribe

1.4.3 (2023-10-07)

• (foxriver76) do not await the subscribes anymore

1.4.2 (2023-09-28)

• (@GermanBluefox) Corrected error by unsubscribing on client disconnect

1.4.1 (2023-09-12)

• (foxriver76) do not cancel follow subscribes if one subscribe has an error

1.4.0 (2023-09-11)

• (foxriver76) fixed crash on invalid patterns with js-controller version 5

1.3.3 (2023-08-01)

• (@GermanBluefox) Implemented subscribing of a client on messages from a specific instance
• (@GermanBluefox) Moved checkFeatureSupported to regular connection and not only admin

1.2.0 (2023-07-07)

• (foxriver76) fixed crash on invalid patterns with js-controller version 5
• (@GermanBluefox) extended the getObjects function with the possibility to read the list of IDs

1.1.5 (2023-03-13)

• (@GermanBluefox) Added command name

1.1.3 (2023-03-12)

• (@GermanBluefox) Treat json5 as json

1.1.2 (2023-03-03)

• (@GermanBluefox) Allow deletion of fullcalendar objects

1.1.1 (2022-12-22)

• (@GermanBluefox) Corrected error with subscription

1.1.0 (2022-12-22)

• (@GermanBluefox) Added user check to many commands
• (@GermanBluefox) Downgrade axios to 0.27.2

1.0.2 (2022-11-08)

• (@GermanBluefox) Function getObjectsfor web was extended by devices, channels and enums

1.0.1 (2022-10-10)

• (@GermanBluefox) Fixed error with delObject

0.5.5 (2022-10-09)

• (Apollon77) Prepare for future js-controller versions

0.5.4 (2022-09-23)

• (@GermanBluefox) Fixed error in delObjects method

0.5.3 (2022-08-24)

• (@GermanBluefox) Caught error by subscribing

0.5.2 (2022-08-19)

• (@GermanBluefox) Added command getCompactSystemRepositories

0.5.0 (2022-07-20)

• (@GermanBluefox) Buffer conversion errors caught and handled

0.4.12 (2022-07-08)

• (@GermanBluefox) Corrected getAdapterInstances method

0.4.11 (2022-07-05)

• (@GermanBluefox) Corrected log transportation

0.4.10 (2022-06-22)

• (@GermanBluefox) Corrected getAdapterInstances

0.4.9 (2022-06-20)

• (@GermanBluefox) Do not show an error with failed authentication

0.4.7 (2022-06-20)

• (@GermanBluefox) Allowed overloading system language

0.4.6 (2022-06-20)

• (@GermanBluefox) updated passport

0.4.5 (2022-06-20)

• (@GermanBluefox) allowed running socket.io behind reverse proxy

0.4.4 (2022-06-09)

• (@GermanBluefox) Do not show the requireLog message

0.4.3 (2022-06-03)

• (@GermanBluefox) Allowed call of getAdapterInstances for non admin

0.4.2 (2022-05-23)

• (@GermanBluefox) Corrected renameFile command for admin

0.4.1 (2022-05-23)

• (@GermanBluefox) Corrected changePassword command for admin

0.4.0 (2022-05-19)

• (@GermanBluefox) Added support of socket.io 4.x

0.3.2 (2022-05-19)

• (@GermanBluefox) Hide warn messages

0.3.1 (2022-05-16)

• (@GermanBluefox) Added back compatibility with js-controller@4.0 for writeDirAsZip

0.3.0 (2022-05-16)

• (@GermanBluefox) Process writeDirAsZip locally

0.2.1 (2022-05-12)

• (@GermanBluefox) fixed getObjects command

0.2.0 (2022-05-09)

• (@GermanBluefox) fixed delObjects command

0.1.10 (2022-05-09)

• (@GermanBluefox) Added support for fileChanges

0.1.9 (2022-05-07)

• (@GermanBluefox) Corrected readLogs command and implement file subscriptions

0.1.7 (2022-05-05)

• (@GermanBluefox) Caught some sentry errors

0.1.6 (2022-05-05)

• (@GermanBluefox) fixed delObject command

0.1.5 (2022-04-25)

• (@GermanBluefox) added updateRatings

0.1.4 (2022-04-24)

• (@GermanBluefox) added passportSocket

0.1.2 (2022-04-24)

• (@GermanBluefox) initial commit

License

The MIT License (MIT)

Copyright (c) 2020-2026 @GermanBluefox dogafox@gmail.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.