Try it out
Walk Through a Real-World Workflow
Connect to a Lobby
We have set up a test lobby for you to try out the robot mode API before integrating with your own lobby. Follow these steps to establish a connection using wscat, a simple WebSocket client for testing:
1. Install wscat
If you don’t already have wscat installed, you can install it globally using npm:
npm install -g wscat
2. Connect to the Test Lobby
You can connect to a virtual version of any lobby by setting the testing parameter to true
Use the following command to establish a WebSocket connection to our test lobby. Replace <API_KEY> with your provided API key and <LOBBY_ID> with the test lobby ID. For this demo we will connect to our test lobby using
Lobby ID: lobby0
API Key: key1
We are going to add the testing parameter to connect to a virtual instance instead.
wscat -c "wss://api.liftauth.com/v2?lobbyId=lobby0&testing=true" -H "Authorization: key1"
3. Send Commands
Once connected, we can send some commands.
Enable Robot Mode
First, we need to enable robot mode to take control of the lobby.
{ "requestId": "req000", "command": "ROBOT_MODE_ON", "parameters": { "reservedLiftId": "lobby0_lift0" } }
You will receive an immediate ROBOT_MODE_ON_OK acknowledgment, followed by a ROBOT_MODE_ENABLED response when robot mode is fully active. Wait for the ROBOT_MODE_ENABLED response before proceeding.
Get Lift Position
Before calling the lift we need to know if the lift is already here.
The lift will fulfill all requests on a best effort basis, meaning it might not be fulfilled immediately.
Copy paste the following into the terminal and wait for a response.
{ "requestId": "req001", "command": "GET_LIFT_POSITION", "parameters": { "liftId": "lobby0_lift0" } }
Assuming the lift is already stationary at the same floor as the robot, we can proceed to enter.
Open the Door
Copy paste the following into the terminal and wait for a response.
{ "requestId": "req002", "command": "SET_DOOR_OPEN", "parameters": { "liftId": "lobby0_lift0" } }
Drive Robot In
This is the stage where you drive the robot into the lift.
Close the Door
Once the robot was in the lift, we can close the door.
Sending the close door request does not close the door immediately. It releases door control back to the lift so the lift system can close the door naturally.
Copy paste the following into the terminal and wait for a response.
{ "requestId": "req003", "command": "SET_DOOR_CLOSE", "parameters": { "liftId": "lobby0_lift0" } }
Send the lift to Floor 1
Once the door is closed, send a request for the lift to travel to that floor.
The lift might not service that floor immediately. It will visit intermediate floors especially if the lift is being shared by human passengers.
Copy paste the following into the terminal and wait for a response.
{ "requestId": "req004","command": "CALL_LIFT","parameters": { "liftId": "lobby0_lift0", "targetFloor": 1, "setOpenOnArrival": false }}
When the lift arrives at a floor, it broadcasts a message to the websocket. Wait until it arrives at your target floor.
After sending CALL_LIFT, you will receive a CALL_LIFT_OK acknowledgment, but you must wait for the CURRENT_FLOOR message to confirm the lift has arrived at the requested floor before proceeding.
Disable Robot Mode
Once you're done with the robot workflow, disable robot mode to release control back to the lobby.
{ "requestId": "req005", "command": "ROBOT_MODE_OFF" }
Cheat Code
And that's it! You have used all the basic commands required for you to control the lift. Now, we will show you how to create a basic script below that allows you to broadcast and listen to the responses before moving on to the next page.
Setting Up npm and Dependencies
Before running the JavaScript file, ensure you have Node.js and npm installed on your system. Follow these steps to set up the required environment:
1. Install Node.js and npm
Download and install Node.js, which includes npm, from the official Node.js website. Follow the installation instructions for your operating system.
2. Initialize a New npm Project
Navigate to your project directory and initialize a new npm project:
mkdir robot-control
cd robot-control
npm init -y
3. Install Required Dependencies
Install the ws package, which is a WebSocket client for Node.js:
npm install ws
4. Save the JavaScript File
Create a new file named robot-control.js in your project directory and copy the following script into it:
const WebSocket = require("ws");
// Replace these with your API Key and Lobby ID
const apiKey = "key1";
const lobbyId = "lobby1";
const testing = "true"; // Enables virtual instance for testing
const endpoint = "wss://api.staging.liftauth.com/";
const wsUrl = `${endpoint}v2?lobbyId=${lobbyId}&testing=${testing}`;
const socket = new WebSocket(wsUrl, {
headers: {
Authorization: apiKey,
},
});
// Store the current step in the workflow
let currentStep = 0;
socket.onopen = () => {
console.log("Connected to WebSocket server.");
runNextStep();
};
socket.onmessage = (event) => {
const response = JSON.parse(event.data);
console.log("Received response:", response);
// Handle responses based on the response code
if (response.code === "ROBOT_MODE_ENABLED" && currentStep === 1) {
console.log("Robot mode enabled and ready");
runNextStep();
} else if (response.code === "GET_LIFT_POSITION_OK" && currentStep === 2) {
console.log("Lift position retrieved:", response.info);
runNextStep();
} else if (response.code === "SET_DOOR_OPEN_OK" && currentStep === 3) {
console.log("Door opened successfully");
runNextStep();
} else if (response.code === "SET_DOOR_CLOSE_OK" && currentStep === 5) {
console.log("Door closed successfully");
runNextStep();
} else if (response.code === "CALL_LIFT_OK" && currentStep === 6) {
console.log("Lift called successfully, waiting for arrival...");
// Note: We wait for the current floor broadcast to confirm arrival
} else if (response.code === "CURRENT_FLOOR" && response.info.currentFloor == 1 && currentStep === 6) {
console.log("Lift arrived at target floor:", response.info);
runNextStep();
} else if (response.code === "ROBOT_MODE_OFF_OK" && currentStep === 7) {
console.log("Robot mode disabled successfully");
runNextStep();
}
};
socket.onclose = () => {
console.log("WebSocket connection closed.");
};
socket.onerror = (error) => {
console.error("WebSocket error:", error);
};
// Function to send a command to the WebSocket server
const sendCommand = (command) => {
console.log("Sending command:", command);
socket.send(JSON.stringify(command));
};
// Function to handle each step in the workflow
const runNextStep = () => {
switch (currentStep) {
case 0:
console.log("\nStep 1: Enable Robot Mode");
sendCommand({
requestId: "req000",
command: "ROBOT_MODE_ON",
parameters: {
reservedLiftId: "lobby0_lift0"
}
});
console.log("Waiting for robot mode to be enabled...");
currentStep++;
break;
case 1:
console.log("\nStep 2: Get Lift Position");
sendCommand({
requestId: "req001",
command: "GET_LIFT_POSITION",
parameters: {
liftId: "lobby0_lift0"
}
});
currentStep++;
break;
case 2:
console.log("\nStep 3: Open the Door");
sendCommand({
requestId: "req002",
command: "SET_DOOR_OPEN",
parameters: {
liftId: "lobby0_lift0"
}
});
currentStep++;
break;
case 3:
console.log("\nStep 4: Drive Robot Into the Lift");
// Simulate robot entering the lift with visual progress
let dots = 0;
const interval = setInterval(() => {
process.stdout.write(".");
dots++;
if (dots >= 5) {
clearInterval(interval);
console.log("\nRobot has entered the lift");
currentStep++;
runNextStep();
}
}, 1000);
break;
case 4:
console.log("\nStep 5: Close the Door");
sendCommand({
requestId: "req003",
command: "SET_DOOR_CLOSE",
parameters: {
liftId: "lobby0_lift0"
}
});
currentStep++;
break;
case 5:
console.log("\nStep 6: Send Lift to Floor 1");
sendCommand({
requestId: "req004",
command: "CALL_LIFT",
parameters: {
liftId: "lobby0_lift0",
targetFloor: 1,
setOpenOnArrival: false
},
});
console.log("Waiting for lift to arrive at target floor...");
currentStep++;
break;
case 6:
console.log("\nStep 7: Disable Robot Mode");
sendCommand({
requestId: "req005",
command: "ROBOT_MODE_OFF",
});
currentStep++;
break;
default:
console.log("\nWorkflow complete");
break;
}
};
5. Run the Script
Execute the script using Node.js:
node robot-control.js
Follow the console output to see the workflow in action.