This package is used by WEB applications and adapters to communicate with ioBroker using websockets and the socket.io protocol.
Important Note: Since v4.0 of this package, pure Websockets are used exclusively! Socket.io is no longer implemented by the socket.io library but simulated via pure WebSockets!
Users can use this package to connect their products to ioBroker via web sockets. Actually, this package could be used by echarts, vis and many other adapters to extract data from ioBroker.
If possible, please use @iobroker/ws-server instead of this package.
By using of socket.io interface user should understand the basics and concept of the system.
It is useful to read about the structure of the objects too.
Object is a description of a data point or group. The group could content other data points in this case it called a channel. If a group consists of other channels, in this case it is called a device.
Object is meta-information that describes data point and could content: max/min value, unit, name, default value, type of value, information for adapter for communication (e.g., ip address) and so on.
State is the actual value of the data point and presented by a JavaScript object:
const state = {
val: VALUE,
ack: ACKNOWLEDGED,
ts: TIMESTAMP, // could be converted into time with "new Date(state.ts)" (In older version of js-controller - "new Date(state.ts * 1000)")
lc: TIMESTAMP_of_last_change,
from: ADAPTER_NAME,
q: QUALITY
}States change themselves very frequently in comparison to the objects. (Normally objects should be changed once by creation, and that's all)
Every state has the attribute ack. It shows the direction of command.
- If ack=false, it means some other adapter wants to control (write) this variable, so that command will be executed (e.g., light will be switched on).
- If ack=true, it means that the device informs about new value. (e.g., light was switched on manually, or motion was detected)
Example: we have some home automation adapter (HAA) that has one lamp connected under address haa.0.lamp1.
- Lamp can be switched on manually with a physical switch or via Wi-Fi with the help of HAA.
- If vis wants to switch the lamp on via Wi-Fi, it should set the new value with
{ value: true, ack: false }. - When the lamp is switched on it is normally informing HAA about new state and the value should be immediately overwritten with
{ value: true, ack: true }. - If the lamp is switched off manually via physical switch it informs HAA about new state with
{ value: false, ack: true }.
Every data point has an attribute q - quality.
You can find the description of every supported method here.
It is suggested to use socket class for communication.
On some web-sockets clients, there is a performance problem with communication. Sometimes this issue is due to the fallback of socket.io communication on a long polling mechanism. You can set the option Force Web-Sockets to force using only web-sockets transport.
- (@GermanBluefox) Fixed: a websocket whose access token was not accepted stayed open without a single
command handler, so the client could not announce the token it had just fetched and waited for an answer
that could not come until its own timeout closed the connection. With authentication enabled, every page
behind this server took seconds to come up after the access token had expired and sometimes did not come
up at all. The fix is in
@iobroker/socket-classes, whose lowest accepted version is raised to 2.6.2
- (@GermanBluefox) Fixed the name of the socket.io transport cookie
- (@GermanBluefox) An undefined ID is no longer published to all clients, but logged as a warning
- (@GermanBluefox) Added tests
- (@GermanBluefox) Updated packages
- (@GermanBluefox) A minimal Node.js version is 22
- (@GermanBluefox) Updated packages
- (@GermanBluefox) Initial commit. Extracted from ioBroker.socketio adapter.
- (@GermanBluefox) A minimal Node.js version is 20
The MIT License (MIT)
Copyright (c) 2014-2026 @GermanBluefox dogafox@gmail.com