Installation Intructions

General Instructions

Include client in HTML

<script src="https://corelink.hsrn.nyu.edu/client/browser/corelink.browser.lib.js"></script>

Include client locally (download first)

<script src="./corelink.browser.lib.js"></script>

Usage Instructions

API reference

API Documentation

Quickstart

1. Authentication

To create a new sender/receiver stream or call any miscellaneous corelink function, you first have to provide the appropriate credentials to be authenticated to the server.

corelink.connect({username: "Testuser", password: "Testpassword"}, {ControlIP: "corelink.hpc.nyu.edu", ControlPort: 20012})

The corelink.connect() function takes two objects as parts of its parameters. The first object contains the username and password attributes, which in the example above holds the values "Testuser" and "Testpassword", respectively. The second object contains the ControlIP and ControlPort attributes. The most commonly used ControlIP or host is the corelink's remote server "corelink.hpc.nyu.edu". In this case, we also choose to use the port 20012 because ...

Once the request is successfully sent, a response {statusCode: 0, token: '6385bfaadfc9297456277259f66445bfa717c28d520f651d318c1b1af47ab1d1', IP: '10.18.151.121'} as such should be returned from the corelink.browser.lib.js file.

2. Sender & Receiver

Inquire our technical-overview to better understand the sender and receiver workflow.

Sender and Receiver explanations can be found here.

3. Others

All functions in the browser client are string-based an can be called using corelink.generic({}).

Examples: Listing all available functions from the corelink browser client

corelink.generic({function: "listFunctions"})

Listing all users registered to the corelink server

corelink.genetic({function: "listUsers"})

Listing the streams correspond to the configured workspace/stream_type/meta.

corelink.generic({function: "listStreams"})

Simple Websocket Sender/Receiver Example Explanation

Follow this walkthrough after you have completed the installation instructions found here

Sender

Global variable senderId

let senderId;

The corelink.createSender() method returns the stream's id which can set to senderId

senderId = corelink.createSender({workspace: 'Holodeck', protocol: 'ws', type: "testdata", echo: false, alert: false})

The TextEncoder().encode() method converts the Javascript string value to an array of type uint8 which we can then pass into corelink.send() along with the streamId to send across the stream

async function send(){
let str = document.getElementById("msg").value;

var uint8array = new TextEncoder().encode(str);
corelink.send(senderId, uint8array)

await sleep(1000)
}

Receiver

corelink.receiver() asks for an object containing the specified workspace, protocol, and stream type of the desired stream

await corelink.createReceiver({ workspace: "Holodeck", protocol: "ws", type: "testdata", echo: true, alert: true }).catch((err) => { console.log(err) })

The corelink.on() is a method used to trigger specific callback function. The corelink.on('receiver', ...) triggers the receiver callback function that returns a data object containing the streamID that you can subscribe to to officially establish a connection with the stream.

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

Using TextDecoder to decode the incoming data in "utf-8" format

corelink.on('data', (streamID, encoding) => {
    var string = new TextDecoder("utf-8").decode(encoding);

    if (string != myString && string!="#"){
        myString = string;
        document.getElementById("msg").innerHTML = string;
    }
})