Installation Instructiosn

General Instructions

One of the following:

npm install corelink-client

Importing

const corelink = require('corelink-client')

Usage Instructions

API reference

API Documentation

TCP Sender and Receiver Walkthrough

Sender Walkthrough

After importing Corelink, you first define some constants. You need a server and a certificate that authenticates into that server in order to send data if you are using a self signed certificate on the server side. If you have a certificate that is signed by a trusted certification authority you only need a server without the need to have a certificate. You will also need to set up Corelink username, password, and most importantly importing it.

const config = {
  ControlPort: 20012,
  /*            ControlIP: '127.0.0.1', */
  ControlIP: 'corelink.hpc.nyu.edu',
  autoReconnect: false,
  /*
    for service in a local network please replace the certificate with the appropriate version
  cert: '<corelink-tools-repo>/config/ca-crt.pem'
  */
}

const username = 'Testuser'
const password = 'Testpassword'

In order to send data, you will also need to define a workspace that you would like to send data into, a name for the stream you will be using, and a protocol to send data with.

The 3 protocols Corelink currently supports are tcp (TCP), udp (UDP), and ws (Web Socket). Any of the three could be used in the protocol field

// Setup

const workspace = 'Holodeck'
const protocol = 'tcp'
const datatype = 'distance'

In our example we have a random data function to just generate some sample data, so here it is.

let iter = 0

function randomdata() {
  iter++
  console.log(iter.toString())
  return iter.toString()
}

This is the function that is actually used to send data. The steps in order are 1. Connect to the server using a username/password and the constansts that we defined before 2. Create a sender that you can send data with 3. Send data with that sender (this is the setInterval() function) 4. Using the Corelink on function to receive call back from receiver, such that the sender will only start sending when at least one receiver is present in the same workspace.

The sender's callback function prevents sending data to an empty workspace. It sets the receiverActive flag to true when a valid receiver is present, ensuring data is only sent when it can be received.

const run = async () => {
  if (await corelink.connect({ username, password }, config).catch((err) => { console.log(err) })) {
    sender = await corelink.createSender({
      workspace,
      protocol,
      type: datatype,
      metadata: { name: 'Random Data' },
    }).catch((err) => { console.log(err) })

    // Provide the sender update callback. 
    corelink.on('sender', (data) => {
      console.log('Sender update:', data)
      if (data.receiverID) {
        receiverActive = true
      } else {
        receiverActive = false
      }
    })

    setInterval(async () => {
      if (receiverActive && sender) {
        const dataToSend = Buffer.from(randomdata());
        await corelink.send(sender, dataToSend);
        console.log('Data sent:', dataToSend.toString());
      }
    }, 1000);

  }
}

run()

Receiver Walkthrough

After importing Corelink, you first define some constants. You need a server and a certificate that authenticates into that server in order to send data if you are using a self signed certificate on the server side. If you have a certificate that is signed by a trusted certification authority you only need a server without the need to have a certificate. You will also need to set up Corelink username, password, and most importantly importing it.

const config = {
  ControlPort: 20012,
  /*            ControlIP: '127.0.0.1', */
  ControlIP: 'corelink.hpc.nyu.edu',
  autoReconnect: false,
  /*
    for service in a local network please replace the certificate with the appropriate version
  cert: '<corelink-tools-repo>/config/ca-crt.pem'
  */
}

const username = 'Testuser'
const password = 'Testpassword'

In order to receive data from our stream, we must be on the same workspace and stream name.

const workspace = 'Holodeck'
const protocol = 'tcp'
const datatype = 'distance'

Receiving data is similar to sending it. Here are the steps: 1. Connect to the server using a username/password 2. create a receiver 3. Define a function that reacts to changes in the stream id 4. Define a callback function to react to the data received.

const run = async () => {
  if (await corelink.connect({ username, password }, config).catch((err) => { console.log(err) })) {
    await corelink.createReceiver({
      workspace, 
      protocol, 
      type: datatype, 
      echo: true, 
      alert: true,
    }).catch((err) => { console.log(err) })

    corelink.on('receiver', async (data) => {
      const options = { streamIDs: [data.streamID] }
      await corelink.subscribe(options)
    })

    corelink.on('data', (streamID, data, header) => {
      console.log(streamID, data.toString(), JSON.stringify(header))

    })
  }
}

run()

One sender can send data to multiple receivers, however it can only send one stream, versus a receiver can receive multiple streams at the same time. These streams are by default from multiple senders as each sender can only send one stream.

Source

You can read the code in the examples repository