dv-js v0.0.4

DV-JS

This is experimental software. No support can be provided. Use at your own risk.

A JavaScript library to connect to the config server and data streams of the dynamic visision stem DV. Runs both in browser as well as in node.

Connects with TCP sockets in node, or websockets in browser. To use with websockets, the tcp connections from DV have to be translated to websockets. For example, using websockify.

Installation

npm install dv-js

Config Server

Connecting

To connect to the DV config tree of a running DV instance:

node.js

const dv = require('dv-js')

// Create a ConfigTree instance
const configTree = new dv.DVConfigTree(
    err => console.error('A communication error occurred: ' + JSON.stringify(err)),  // Custom error handler, optional
    () => console.log('Connection to DV config tree dropped')                        // Custom disconnect handler, optional
)

// Connect with TCP (nodejs)
configTree.connect('tcp', {host: '127.0.0.1', port: 4040}).then(() => {
    console.log('Connected')
})

Browser

import { DVConfigTree } from 'dv-js'

// Create a ConfigTree instance
const configTree = new DVConfigTree(
    err => console.error('A communication error occurred: ' + JSON.stringify(err)),  // Custom error handler, optional
    () => console.log('Connection to DV config tree dropped')                        // Custom disconnect handler, optional
)

// Connect with websocket (browser)
configTree.connect('websocket', {url: 'ws://127.0.0.1/ws'}).then(() => {
    console.log('Connected')
})

Promises

The connect function returns a promise. You can also use it with async/await

async function setup() {
    ....
    await configTree.connect('tcp', {host: '127.0.0.1', port: 4040})
    console.log('Connected!')
    ....
}

Reading values

The API does not discern between nodes and attributes. A value is addressed by <node>/<attribute>. For example:

• /system/ user -> /system/user
• /mainloop/myModule/ myAttribute -> /mainloop/myModule/myAttribute

To read a value from the config tree, use the get function. The function returns a promise with the value.

// Callback based
configTree.get('/mainloop/myModule/myAttribute').then(value => console.log(value))

// async / await
const value = await configTree.get('/mainloop/myModule/myAttribute')

Setting values

To set values in the config tree use the put function. The put function returns a promise, that resolves as soon as the value is correctly set in the dv runtime.

// Callback based
configTree.get('/mainloop/myModule/myAttribute').then(() => console.log('value set!'))

// async / await
await configTree.put('/mainloop/myModule/myAttribute')
console.log('value set')

Reacting to push changes

You can set a handler for changes that are made in the DV config tree. The handler gets called whenever a module, the system or another client performs a change in the DV config tree. To add a handler to these push notifications, use the onPushChange function.

configTree.onPushChange((path, value) => {
    console.log(`Attribute ${path} changed to ${value}`)
})

Receiving data

dv-js provides functionality to receive data sent out via TCP from DV. To set up, make sure to add a dv output net tcp module to your structure configuration, that you connect to the data you want to receive in JS.

Frames

To connect to a frame output, use the following:

node.js

const dv = require('dv-js')

function handleNewFrame(frame, channels) {
    const pixels = frame.pixelsArray()
    const width = frame.sizeX()
    const height = frame.sizeY()

    // more processing with frame, like rendering etc.
    ....
}

// Create a FrameChannel instance
const frameChannel = new dv.DVFrameChannel(
    handleNewFrame, // function that handles a new frame
    err => console.error('A communication error occurred: ' + JSON.stringify(err)),  // Custom error handler, optional
    () => console.log('Connection to DV config tree dropped')                        // Custom disconnect handler, optional
)

// Connect with TCP (nodejs)
frameChannel.connect('tcp', {host: '127.0.0.1', port: 7777}).then(() => {
    console.log('Connected')
})

Browser

import { DVFrameChannel } from 'dv-js'

function handleNewFrame(frame, channels) {
    const pixels = frame.pixelsArray()
    const width = frame.sizeX()
    const height = frame.sizeY()

    // more processing with frame, like rendering etc.
    ....
}

// Create a FrameChannel instance
const frameChannel = new DVFrameChannel(
    handleNewFrame, // function that handles a new frame
    err => console.error('A communication error occurred: ' + JSON.stringify(err)),  // Custom error handler, optional
    () => console.log('Connection to DV config tree dropped')                        // Custom disconnect handler, optional
)

// Connect with websocket (browser)
frameChannel.connect('websocket', {url: 'ws://127.0.0.1/wsframes'}).then(() => {
    console.log('Connected')
})

Any other data type

dv-js does not provide any other data types built in at this stage. However, it is easy to extend it to other data types, even custom ones by writing your own class.

• Generate the js api for the flatbuffers definition of your data type
• Extend DVDataChannel, implement the _parsePacket function

import { dv as mydataFb } from './mydata_generated' // your generated js file from flatbuffers
import { DVDataChannel } from 'dv-js'

class MyDataChannel extends DVDataChannel {

    constructor(dataHandler, commErrorHandler=null, disconnectHandler=null) {
        super(commErrorHandler, disconnectHandler)
        // handles incoming frames
        this._dataHandler = dataHandler
    }

    // Implement this function. It gets called whenever a new flatbuffers packet arrives
    _parsePacket(data) {
        // Parse the packet with your flatbuffer definition
        const packet = mydataFb.MyData.getRootAsFrame(data)
        // invoke handler with the new packet
        this._dataHandler(packet)
    }
}

export default MyDataChannel

Then, you can use your class exactly like the DVFrameChannel class for obtaining your data.