resol-vbus-core

Appearance

Introducing Toolbox Scripts and Configuration ​

The resol-vbus-core-toolbox is a Node.js-based scripting utility that allows a user to connect to one or more RESOL VBus data sources (e.g. using VBus-over-TCP or a serial port) and run custom scripts written in TypeScript to process VBus data or interact with connected devices.

The resol-vbus-core-toolbox itself uses several libraries from the resol-vbus-core* ecosystem:

  • resol-vbus-core, resol-vbus-core-nodejs and resol-vbus-core-vsf can be used from inside the custom scripts
  • resol-vbus-core-script provides the underlying interfaces and utility functions to parse and run the custom scripts

The structure of a script ​

resol-vbus-core-script expects the custom scripts to use the following structure:

typescript
// optionally: import other scripts here to use their services
// import otherScript from './other-script';

export default defineScript(async ($) => {
  // optionally: perform initialization here, e.g.
  // $.onPacket((packet) => { ... });

  // optionally: require the service from another script and use it
  // const otherService = await otherScript.requireService();
  // ...

  // optionally: register a service for this script that other scripts can use
  // $.registerService(...):

  await $.connect();

  // optionally, when done:
  // await $.disconnect();
});

The defineScript function is provided by the scripting environement (e.g. resol-vbus-core-toolbox). defineScript takes a single argument: an async function that actually runs the custom script.

That script function is called with a $ argument passed once the script is actually run, giving the script access to the RESOL VBus data sources, event listeners and other utility functions for interacting with the VBus data.

The $.registerService() function and otherScript.requireService() function can be used to provide and consume services between different scripts.

The $.connect() function is synchronized between all running scripts. $.connect will pause execution of the current script until all scripts have called their respective $.connect function and all connections to the configured VBus data sources have been successfully established.

The script continous to run (even after the function passed to defineScript has returned), until:

The structure of a configuration file ​

resol-vbus-core-toolbox uses a configuration file to specify which connections to establish and which scripts to load. The configuration file has the following structure:

typescript
export default defineConfig({
  connections: [
    {
      kind: 'net',
      options: {
        socketOptions: {
          host: '127.0.0.1',
          port: 7053,
        },
      },
    },
    {
      kind: 'serialport',
      path: '/dev/tty.usbmodem1',
    },
  ],
  scripts: [
    import('../scripts/first-script'),
    import('../scripts/second-script'),
  ],
});

Connections ​

resol-vbus-core-toolbox currently supports three kind of connections: virtual, net and serialport.

Virtual connections ​

Virtual connections are in-memory loopback connections that are ideal for testing. See the VirtualConnectionConfig interface for details on configuration.

typescript
    ...
    {
      kind: 'virtual',
      options: {
        // any `LiveTransceiverConstructorOptions` here
      },
    },
    ...

Network-based connections ​

Network-based connection use TCP sockets to connect to a RESOL VBus data source, optionally performing the VBus-over-TCP handshake first. See the NetConnectionConfig interface for details on configuration.

typescript
    ...
    {
      kind: 'net',
      options: {
        socketOptions: {
          host: '127.0.0.1',
          port: 7053,
        },
        // any `NetLiveTransceiverConstructorOptions` here
      },
    },
    ...

Serial port based connections ​

Since the RESOL VBus is a serial connection using a non-standard set of voltage level, serial port based connections allow you to access RESOL VBus data over such a raw serial port connection, regardless whether it is provided by the RESOL VBus/USB adapter or a custom made solution. See the SerialPortConnectionConfig interface for details on configuration.

typescript
    ...
    {
      kind: 'serialport',
      path: `/dev/tty.usbmodem1`,
      options: {
        // any `LiveTransceiverConstructorOptions` here
      },
    },
    ...

Scripts ​

The configuration provides multiple ways to load scripts:

  • top-level import statement and passing the imported script
  • inline import() function call, passing the Promise for the imported script
  • use defineScript() to define a script inline

Top-level import statement ​

typescript
import otherScript from '../scripts/other-script';

export default defineConfig({
  ...
  scripts: [
    ...
    otherScript,
    ...
  ],
  ...
});

import() function ​

typescript
export default defineConfig({
  ...
  scripts: [
    ...
    import('../scripts/other-script'),
    ...
  ],
  ...
});

Inline defineScript() ​

typescript
export default defineConfig({
  ...
  scripts: [
    ...
    defineScript(async ($) => {
      // your script code here
    }),
    ...
  ],
  ...
});