ioBroker server-side web sockets
npm install @iobroker/socket-classesThis library is used at least for the following adapters:
- iobroker.admin
- iobroker.cloud
- iobroker.socketio
- iobroker.ws
- iobroker.rest-api
- iobroker.iot
js
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)
`js
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
GUI client can send to desired instance the subscribe message
`js
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.
`js
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 client will receive messages from instance
`js
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
$3
* authenticate
* updateTokenExpiration
* error
* log
* checkFeatureSupported
* getHistory
* httpGet
* sendTo
* sendToHost
* authEnabled
* logout
* listPermissions
* getUserPermissions
* getVersion
* getAdapterName
* clientSubscribe
* clientUnsubscribe
* getAdapterInstances
* getObject
* getObjects
* 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
$3
#### 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) => voidupdateTokenExpiration(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) => voiderror(error)
Write error into ioBroker log
error Error | string*: Error object or error textlog(text, level)
Write log entry into ioBroker log
text string*: log text
level ioBroker.LogLevel*: one of ['silly', 'debug', 'info', 'warn', 'error']. 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) => voidgetHistory(id, options, callback)
Get history data from 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) => voidhttpGet(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) => voidsendTo(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) => voidsendToHost(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 }) => voidauthEnabled(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) => voidlogout(callback)
Logout user
callback ioBroker.ErrorCallback*: callback (error?: Error) => voidlistPermissions(callback)
List commands and permissions
callback (permissions: Record< string, {type: 'object' | 'state' | 'users' | 'other' | 'file' | ''; operation: SocketOperation} >) => void*: callback (permissions: RecordgetUserPermissions(callback)
Get user permissions
callback (error: string | null | undefined, userPermissions?: SocketACL | null) => void) => void*: callback (error: string | null | undefined, userPermissions?: SocketACL | null) => voidgetVersion(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) => voidgetAdapterName(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) => voidclientSubscribe(targetInstance, messageType, data, callback)
Client subscribes to specific instance's messages.
Client informs specific instance about subscription on its messages.
After subscription, the socket will receive "im" messages from 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; }) => voidclientUnsubscribe(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) => voidgetAdapterInstances(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$3
#### 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) => voidgetObjects(list, callback)
Get all objects that are relevant for web: all states and enums with rooms.
This is 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) => void) => void*: Callback (error: string | null, objs?: RecordsubscribeObjects(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) => voidunsubscribeObjects(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) => voidgetObjectView(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: ArraysetObject(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) => voiddelObject(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$3
#### 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) => void) => void*: callback (error: null | undefined | Error | string, states?: RecordgetForeignStates(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) => void) => void*: callback (error: null | undefined | Error | string, states?: RecordgetState(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) => voidsetState(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) => voidgetBinaryState(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) => voidsetBinaryState(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) => voidsubscribe(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) => voidsubscribeStates(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) => voidunsubscribe(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) => voidunsubscribeStates(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$3
#### 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) => voidreadFile64(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) => voidwriteFile64(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) => voidwriteFile(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) => voidunlink(adapter, name, callback)
Delete 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) => voiddeleteFile(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) => voiddeleteFolder(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) => voidrenameFile(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) => voidrename(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) => voidmkdir(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) => voidreadDir(adapter, dirName, options, callback?)
Read content of 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}}>) => voidchmodFile(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) => voidchownFile(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 owner.
callback? (error: null | undefined | Error | string) => void*: Callback (error: null | undefined | Error | string) => voidfileExists(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) => voidsubscribeFiles(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) => voidunsubscribeFiles(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) => voidAdmin Methods
$3
* authenticate
* updateTokenExpiration
* error
* log
* checkFeatureSupported
* getHistory
* httpGet
* sendTo
* sendToHost
* authEnabled
* logout
* listPermissions
* getUserPermissions
* getVersion
* getAdapterName
* clientSubscribe
* clientUnsubscribe
* getAdapterInstances
* getHostByIp
* requireLog
* readLogs
* cmdExec
* eventsThreshold
* getRatings
* getCurrentInstance
* decrypt
* encrypt
* getIsEasyModeStrict
* getEasyMode
* getAdapters
* updateLicenses
* getCompactInstances
* getCompactAdapters
* getCompactInstalled
* getCompactSystemConfig
* getCompactSystemRepositories
* getCompactRepository
* getCompactHosts
* delState
* getStates
* getForeignStates
* getState
* setState
* getBinaryState
* setBinaryState
* subscribe
* subscribeStates
* unsubscribe
* unsubscribeStates
* addUser
* delUser
* addGroup
* delGroup
* changePassword
* getObject
* getObjects
* subscribeObjects
* unsubscribeObjects
* getObjectView
* setObject
* delObject
* getAllObjects
* extendObject
* getForeignObjects
* delObjects
* readFile
* readFile64
* writeFile64
* writeFile
* unlink
* deleteFile
* deleteFolder
* renameFile
* rename
* mkdir
* readDir
* chmodFile
* chownFile
* fileExists
* subscribeFiles
* unsubscribeFiles
$3
#### 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) => voidupdateTokenExpiration(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) => voiderror(error)
Write error into ioBroker log
error Error | string*: Error object or error textlog(text, level)
Write log entry into ioBroker log
text string*: log text
level ioBroker.LogLevel*: one of ['silly', 'debug', 'info', 'warn', 'error']. 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) => voidgetHistory(id, options, callback)
Get history data from 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) => voidhttpGet(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) => voidsendTo(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) => voidsendToHost(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 }) => voidauthEnabled(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) => voidlogout(callback)
Logout user
callback ioBroker.ErrorCallback*: callback (error?: Error) => voidlistPermissions(callback)
List commands and permissions
callback (permissions: Record< string, {type: 'object' | 'state' | 'users' | 'other' | 'file' | ''; operation: SocketOperation} >) => void*: callback (permissions: RecordgetUserPermissions(callback)
Get user permissions
callback (error: string | null | undefined, userPermissions?: SocketACL | null) => void) => void*: callback (error: string | null | undefined, userPermissions?: SocketACL | null) => voidgetVersion(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) => voidgetAdapterName(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) => voidclientSubscribe(targetInstance, messageType, data, callback)
Client subscribes to specific instance's messages.
Client informs specific instance about subscription on its messages.
After subscription, the socket will receive "im" messages from 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; }) => voidclientUnsubscribe(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) => voidgetAdapterInstances(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$3
#### 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) => voidrequireLog(isEnabled, callback?)
Activate or deactivate logging events. Events will be sent to the socket as log event. Adapter must have common.logTransporter = true.
isEnabled boolean*: - Is logging enabled
callback? (error: string | null | Error | undefined) => void*: - Callback function (error: string | null) => voidreadLogs(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 }[]) => voidcmdExec(host, id, cmd, callback?)
Execute the shell command on host/controller.
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
callback? (error: string | null | Error | undefined) => void*: - Callback function (error: string | null) => voideventsThreshold(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 limitedgetRatings(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) => voidgetCurrentInstance(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) => voiddecrypt(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) => voidencrypt(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) => voidgetIsEasyModeStrict(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) => voidgetEasyMode(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[] }) => voidgetAdapters(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[]) => voidupdateLicenses(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[]) => voidgetCompactInstances(callback)
Get all instances in a compact form to save bandwidth.
callback (error: string | null | Error | undefined, result?: Record) => void) => void*: - Callback function (error: string | null, results?: RecordgetCompactAdapters(callback)
Get all adapters in a compact form to save bandwidth.
callback (error: string | null | Error | undefined, result?: Record) => void) => void*: - Callback function (error: string | null, results?: RecordgetCompactInstalled(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) => void) => void*: - Callback function (error: string | null, results?: RecordgetCompactSystemConfig(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 } }) => voidgetCompactSystemRepositories(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: RecordgetCompactRepository(host, callback)
Get the repository in a compact form to save bandwidth.
host string*: - Host name, e.g., system.host.raspberrypi
callback (result: Record) => void) => void*: - Callback function (error: string | null, results?: RecordgetCompactHosts(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$3
#### 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) => voidgetStates(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) => void) => void*: callback (error: null | undefined | Error | string, states?: RecordgetForeignStates(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) => void) => void*: callback (error: null | undefined | Error | string, states?: RecordgetState(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) => voidsetState(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) => voidgetBinaryState(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) => voidsetBinaryState(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) => voidsubscribe(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) => voidsubscribeStates(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) => voidunsubscribe(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) => voidunsubscribeStates(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$3
#### 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) => voiddelUser(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) => voidaddGroup(group, desc, acl, callback?)
Add a new group.
group string*: - Group name, e.g., users
desc ioBroker.StringOrTranslated | null*: - Optional description
acl Omit | 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) => voiddelGroup(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) => voidchangePassword(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$3
#### 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) => voidgetObjects(list, callback)
Get all objects that are relevant for web: all states and enums with rooms.
This is 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) => void) => void*: Callback (error: string | null, objs?: RecordsubscribeObjects(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) => voidunsubscribeObjects(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) => voidgetObjectView(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: ArraysetObject(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) => voiddelObject(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) => voidgetAllObjects(callback)
Read absolutely all objects.
callback (error: null | undefined | Error | string, result?: Record) => void) => void*: - Callback function (error: string | null, objects?: RecordextendObject(id, obj, callback?)
Extend the existing object.
id string*: - Object ID
obj Partial*: - New parts of the object, e.g., {common: {name: 'new name'}}
callback? (error: string | null | Error | undefined) => void*: - Callback function (error: string | null) => voidgetForeignObjects(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) => void)*: - Type of objects to delete, like state, channel, device, host, adapter. Default - state
callback? (error: string | null | Error | undefined, objects?: Record) => void*: - Callback function (error: string | null, objects?: RecorddelObjects(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$3
#### 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) => voidreadFile64(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) => voidwriteFile64(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) => voidwriteFile(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) => voidunlink(adapter, name, callback)
Delete 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) => voiddeleteFile(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) => voiddeleteFolder(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) => voidrenameFile(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) => voidrename(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) => voidmkdir(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) => voidreadDir(adapter, dirName, options, callback?)
Read content of 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}}>) => voidchmodFile(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) => voidchownFile(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 owner.
callback? (error: null | undefined | Error | string) => void*: Callback (error: null | undefined | Error | string) => voidfileExists(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) => voidsubscribeFiles(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) => voidunsubscribeFiles(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
$3
* (@Copilot) Added missing return statement for Bearer token auth
$3
* (@GermanBluefox) Fixed change of the language in the admin
$3
* (@GermanBluefox) Added an option to disable filling of
info.connected$3
* (@GermanBluefox) Send
reauthenticate command if token expired$3
* (@GermanBluefox) Typing improvement
$3
* (@GermanBluefox) Make secret optional for cloud usage
$3
* (@GermanBluefox) Make objects optional for
SocketAdmin$3
* (@GermanBluefox) Removed debug text
$3
* (@GermanBluefox) Deliver vendor information in
getCompactSystemConfig` command* (@GermanBluefox) Changed the order of authentications. Basic authentication will be checked as the last one.
* (@GermanBluefox) Added the setting to disable basic authentication