Accessing VBus over TCP/IP

The resol-vbus-core-nodejs library exports a NetLiveTransceiver class that provides access to VBus data using VBus-over-TCP.

This allows software to access interfaces like e.g. RESOL's DL2 Plus both locally or over the VBus.net cloud service.

A small example project

Let's create a small example project as a starting point for connecting to a TCP-enabled interface:

# create a new working directory and use it as a working directory for the remainder of the guide
mkdir net-vbus-test
cd net-vbus-test

# create a minimal `package.json` file
yarn init -y

# install dependencies using your package manager of choice (here: yarn)
yarn add resol-vbus-core resol-vbus-core-nodejs

# create an empty `src/main.js` for the actual code
mkdir src
touch src/main.js

Then start editing your src/main.js and import the required dependencies:

const { NetLiveTransceiver } = require('resol-vbus-core-nodejs');

Create a main function to place all other async code into and execute it, handling all errors by printing them and exiting the program:

async function main() {
  // TODO: place all other code into here
}

main().then(null, (error) => {
  console.error(error);
  process.exit(1);
});

Inside the main function create a new NetLiveTransceiver instance:

const options = {
  // TODO: the options will be filled later
};

// Create a `NetLiveTransceiver` instance
const tx = new NetLiveTransceiver(options);

After that the connect method of the NetLiveTransceiver can be used to start the VBus-over-TCP handshake in order to establish a VBus connection:

// Start the VBus-over-TCP handshake
await tx.connect();

The options roughly consist of three parts:

• the socketOptions that are passed to Node.js net.createConnection() function,
• the liveTransceiverOptions that are passed to the LiveTransceiver super constructor, and
• NetLiveTransceiver specific options, mainly for the VBus-over-TCP handshake.

const options = {
  // `socketOptions`: see Node.js documentation for `net.createConnection(options)`
  //
  // Link: https://nodejs.org/dist/v24.0.0/docs/api/net.html#netcreateconnectionoptions-connectlistener
  socketOptions: {
    // `port` is required and should be set to `7053`
    port: 7053,

    // `host` is optional, but since it defaults to `localhost` it must normally be provided
    host: '192.168.178.100',
  },

  // `liveTransceiverOptions`: see `resol-vbus-core` documentation for
  // options passed to the constructor of `LiveTransceiver`
  //
  // Link: https://resol-vbus-core.bugstu.be/api/resol-vbus-core.livetransceiverconstructoroptions.html
  liveTransceiverOptions: {
    // `onPacket` provides a callback that is called for every received VBus v1 Packet.
    onPacket: (packet) => {
      console.log(packet.getId());
    },

    // other options include `onDatagram`, `onTelegram`, `onJunkData` etc.
  },

  // other options related to the VBus-over-TCP handshake
  //
  // Link: https://resol-vbus-core.bugstu.be/api/resol-vbus-core-nodejs.netlivetransceiverconstructoroptions.html

  // // The `viaTag` option for connecting through the VBus.net cloud service
  // viaTag: 'mydl2plus',

  // // The `channel` option to select a VBus channel on interfaces that support more than one
  // channel: 2,

  // The `password` option for authenticating at the interface
  password: 'vbus',

  // The `onConnectionStateChange` provides a callback that is called when the VBus-over-TCP state machine
  // changes its state (e.g. establishing or interrupting the connection)
  onConnectionStateChange: (newConnectionState) => {
    console.log({ newConnectionState });
  },};

The complete code example looks like this:

const { NetLiveTransceiver } = require('resol-vbus-core-nodejs');

async function main() {
  const options = {
    // `socketOptions`: see Node.js documentation for `net.createConnection(options)`
    //
    // Link: https://nodejs.org/dist/v24.0.0/docs/api/net.html#netcreateconnectionoptions-connectlistener
    socketOptions: {
      // `port` is required and should be set to `7053`
      port: 7053,

      // `host` is optional, but since it defaults to `localhost` it must normally be provided
      host: '192.168.178.100',
    },

    // `liveTransceiverOptions`: see `resol-vbus-core` documentation for
    // options passed to the constructor of `LiveTransceiver`
    //
    // Link: https://resol-vbus-core.bugstu.be/api/resol-vbus-core.livetransceiverconstructoroptions.html
    liveTransceiverOptions: {
      // `onPacket` provides a callback that is called for every received VBus v1 Packet.
      onPacket: (packet) => {
        console.log(packet.getId());
      },

      // other options include `onDatagram`, `onTelegram`, `onJunkData` etc.
    },

    // other options related to the VBus-over-TCP handshake
    //
    // Link: https://resol-vbus-core.bugstu.be/api/resol-vbus-core-nodejs.netlivetransceiverconstructoroptions.html

    // // The `viaTag` option for connecting through the VBus.net cloud service
    // viaTag: 'mydl2plus',

    // // The `channel` option to select a VBus channel on interfaces that support more than one
    // channel: 2,

    // The `password` option for authenticating at the interface
    password: 'vbus',

    // The `onConnectionStateChange` provides a callback that is called when the VBus-over-TCP state machine
    // changes its state (e.g. establishing or interrupting the connection)
    onConnectionStateChange: (newConnectionState) => {
      console.log({ newConnectionState });
    },
  };

  // Create a `NetLiveTransceiver` instance
  const tx = new NetLiveTransceiver(options);

  // Start the VBus-over-TCP handshake
  await tx.connect();
}

main().then(null, (error) => {
  console.error(error);
  process.exit(1);
});

To run it, just execute:

> node src/main.js
{ newConnectionState: 'connecting' }
{ newConnectionState: 'connected' }
00_0010_1911_10_0100
...

Good job! You now have access to the VBus data and can either passively wait for incoming data or actively start communicating with VBus participants.