Node-Switcher

Node-Switcher is the native NodeJS add-on for Switcher. It acts as a thin wrapper around Switcher's C++ API, allowing it to be included in Javascript applications. In the context of the Scenic stack, Node-Switcher is the link allowing Scenic Core to communicate with Switcher.

Node-Switcher is currently developed by the Société des Arts Technologiques [SAT], a non-profit artistic entity based in Montreal, CA. The current version of Node-Switcher has been tested with Ubuntu 18.04.

Installation

Dependencies

IMPORTANT: Take note that Node-Switcher 3.2.x is only compatible with Switcher 2.1.24 and up. Use Node-Switcher 3.1.2 if you plan to use a version of Switcher lower than 2.1.24.

| Name | Version | Command | Description | |----------------------------------|-------------|---------|-----------------------------------------------------------------------| | G++/GCC | >= 8 | sudo apt-get install gcc-8 g++-8 | GNU project C and C++ compiler | | libicu-dev | latest | sudo apt install libicu-dev | Development library for handling of unicode characters | | Git | latest | sudo apt-get install git | Distributed version control system used to get Node-Switcher source code | | NodeJS | >= 10.15.3 | See NodeJS installation instructions | JavaScript runtime which helps to build the Scenic engine | | NPM | >= 5.6.0 | Included with the NodeJS installation | JavaScript package manager used to build internal dependencies | | Shmdata | >= 1.3.32 | See Shmdata documentation | Library to share flows of data frames between processes via shared memory | | Switcher | >= 2.1.24 | See Switcher documentation | C++ engine allowing the streaming of data over IP networks |

Install with Scenic Core

Node-Switcher is specified as a dependency in Scenic Core's package.json. This means that Node-Switcher will be automatically downloaded, built and installed as part of Scenic Core's install process.

See Scenic Core's installation procedure for more information.

Install from Source

| Step | Command |------------------------------------|------------------------- | Clone the Node-Switcher repository | git clone [email protected]:sat-mtl/telepresence/node-switcher.git | Move into Node Switcher folder | cd node-switcher | Build the app | npm install

Additional Scripts

Additional NPM scripts are available to build the add-on:

node-gyp configure # configure node-gyp (optionnal)

npm run build
npm run build:debug # build for debug
npm run rebuild
npm run rebuild:debug # rebuild for debug

Install from Docker

The default Docker configuration uses the images built from Switcher. Docker-compose will fetch the develop branches from shmdata, switcher and node-switcher.

# Build the whole stack
docker-compose -f container/docker-compose.yml up

Build a Docker image

To build a Docker image of Node-Switcher, you'll need to build the Shmdata and Switcher images beforehand..

# Build node-switcher's image
docker build -t "node-switcher:develop" .

The node-switcher image uses [mutli-stage builds][docker-multi-stage] with 4 stages : dependencies, nodejs, build and clean. Theses stages use some build arguments :

| arguments | stages | description | default | |-----------------|---------------------|------------------------------------------|-----------------| | SWITCHER_IMAGE | dependencies | The switcher base image | registry.gitlab.com/sat-metalab/switcher | SWITCHER_TAG | dependencies | The tag of the switcher base image | develop | NODEJS_VERSION | nodejs | NodeJS version to use | 10 | NODEJS_DOWNLOAD | nodejs | Link to the NodeJS binary | https://deb.nodesource.com/setup_${NODEJS_VERSION}.x | BUILD_DIR | build and clean | Where node-switcher source is copied | /opt/node-switcher

The node-switcher instance could be executed directly with its REPL :

docker run -ti node-switcher:develop node-switcher-repl

Usage

Javascript Scripting

Node-Switcher allows you to write JavaScript scripts to control Switcher. For example, you can use it to create quiddities, change a quiddity's properties, establish SIP communication with others, etc.

Example:

const Switcher = require('node-switcher').Switcher

const sw = new Switcher('debug', console.log)

// create a new quiddity `jacksrc`
sw.create('jacksrc')

You can see all examples in the folder example.

REPL Interface

You can also use a Read-Eval-Print Loop (REPL) in order to test Node-Switcher in the terminal. Type the following command in your terminal to do so:

# Inside node-switcher/
./bin/repl.js

Debugging

The following Visual Studio Code debug task can help you debug Node-Switcher. lldb and the vadimcn.vscode-lldb VSCode extension must be installed before running this task.

{
  "configurations": [{
    "name": "Node Switcher (lldb)",
    "type": "lldb",
    "request": "launch",
    "program": "${env:HOME}/.bin/node",
    "args": [
      "${workspaceFolder:node-switcher}/examples/debug.js"
    ],
    "preLaunchTask": "npm: build:dev"
  }]
}

Technologies

This add-on uses C++ 17 and NodeJS >= 10.

The SAT uses Ubuntu 18.04, so testing priority is given to this version.

Documentation

The NodeJs API is documented with source comments into cpp files. The documentation can be generated with JSDoc by running the command :

npm run doc

Contributing

Check out our Contributing Guide to get started!

Versioning

SemVer is used for versioning. For the versions available, see the tags on this repository.

Authors

See here.

License

This project is licensed under the GNU General Public License version 3 - see the LICENSE file for details.

Acknowledgments

This project was made possible by the Société des Arts Technologiques [SAT].