server/README.md

HapticTouch Server

The HapticTouch server is a NodeJS/TypeScript WebSocket and Express server used to manage HapticTouch.

Instructions

git clone https://github.com/AnujPanthri/HapticLink
cd HapticLink/server
npm install
npm run dev

To build use: npm run build

To run use: npm start

Documentation

Both HTTP and WebSocket server are running on the same port

WebSocket API

WebSockets payload will be in JSON and require atleast a route property. Types can be client -> server, server -> client <private | room>. Private messages are sent directly to the client. Room messages are sent to everyone in a room.

Get Pong

Type: client -> server
Description: Used to get pong message from server when requested. This can be used to detect when a client is disconnected from the server. Payload:

{
    "route": "get_pong",
}

Type: server -> client <private>
Payload:

{
    "message": "pong",
}

Get User Info

Type: client -> server
Payload:

{
    "route": "get_user_info",
}

Type: server -> client <private>
Payload:

{
    "message": "set_username_response",
    "status": string,
    "user": {
        "username": string,
        "id": string,
        "currentRoom": string,
    }
}

Join Room

Type: client -> server
Description: Used to enter a room. Join an existing room by including roomId, or if room doesn't exist, create one with a random ID
Payload:

{
    "route": "join_room",
    "roomId"?: string, // Room Id, optional
    "username"?: string,
}

Type: server -> client <private>
Payload (only sent if there's an error, else room_update is sent):

{
    "message": "join_room_response",
    "status": string,
}

Leave Room

Type: client -> server
Description: Used to leave a room.
Payload:

{
    "route": "leave_room",
    "roomId": string; // Room Id, optional
}

Type: server -> client <private>
Payload:

{
    "message": "leave_room_response",
    "status": string,
}

Receive Touch

Type: server -> client <room>
Description: Broadcasted to all members of a room when any user sends a successful send_touch request
Payload:

{
    "message": "receive_touch",
    "id": string, // format: [userID]_[id]
    "type": "enable" | "disable", // Whether the vibration is active or not.
    "user": {
        username: string,
        id: string,
    },
    "position": {
        x: number,
        y: number,
    },
    "color": string, // Hex value.
    "intensity": number, // Vibration intensity.
}

Send Touch

Type: client -> server
Description: Used to send touch/vibration data to room. Client assigns a number for an ID. That ID is then used to update the vibration. Re-use send_touch to update previous vibration. Use "type": "disable" to disable the vibration. If an update isn't sent within 1 second of creation/last update it should automatically be disabled.
Payload:

{
    "route": "send_touch",
    "id": number, // Used to indentify vibrations for updating or disabling them, generated by client. Doesn't need to be secure.
    "type": "enable" | "disable", // Whether the vibration is active or not.
    "position": {
        x: number,
        y: number,
    },
    "color"?: string, // Hex value. Default: random
    "intensity"?: number, // Vibration intensity. Default: 1
}

Type: server -> client <private>
Payload:

{
    "message": "set_username_response",
    "status": string,
}

Test Connection

Type: client -> server
Payload:

{
    "route": "test_connection"
}

Type: server -> client <private>
Response:

{
    "message": "test_connection_response",
}

Room Update

Type: server -> client <room>
Description: Server message that is sent when the room gets updated such as someone joins or leaves
Payload:

{
    "message": "room_update",
    "roomId": string,
    "users": [{
        username: string,
        id: string,
        online: boolean,
        lastOnline: number, // ms epoch time
    }],
}

Send Touch

Type: client -> server
Description: Used to send touch/vibration data to room. Client assigns a number for an ID. That ID is then used to update the vibration. Re-use send_touch to update previous vibration. Use "type": "disable" to disable the vibration. If an update isn't sent within 1 second of creation/last update it will automatically be disabled.
Payload:

{
    "route": "send_touch",
    "id": number, // Used to indentify vibrations for updating or disabling them
    "type": "enable" | "disable", // Whether the vibration is active or not.
    "position": {
        x: number,
        y: number,
    },
    "color"?: string, // Hex value. Default: random
    "intensity"?: number, // Vibration intensity. Default: 1
}

Set Username

Type: client -> server
Description: Used to set username. Payload:

{
    "route": "set_username",
    "username": string,
}

Get Rooms

WARNING: not implemented yet

Type: client -> server
Description: Used to get list of joined rooms
Payload:

{
    "route": "get_rooms"
}

Type: server -> client <private>
Payload:

{
    "message": "get_rooms_response",
    "rooms": [{id: string, userCount: number}]
}

API

GET /
Responds with homepage.